跳至主要内容

Salesforce

此页面包含 Salesforce 来源连接器的设置指南和参考信息。

先决条件

  • 具有 Enterprise 版本 Professional 版本且已购买 API 访问权限的 Salesforce 帐户

您可能还需要以下内容。本文档介绍了如何获取它们。

  • 对于 Airbyte 开源版:Salesforce OAuth 凭据

设置指南

创建专用的 Salesforce 用户(可选,但建议)

请按照以下说明创建最低访问权限标准配置文件,并分配自定义权限集,以授予新用户读取您希望使用 Airbyte 访问的数据所需的权限。

虽然您可以使用具有读取权限的任何 Salesforce 用户设置 Salesforce 连接器,但我们建议创建一个专用的用户,该用户具有 Airbyte 的最低访问权限标准配置文件。这使您可以细粒度地控制 Airbyte 可以读取的数据。

使用权限集,您应授予此用户读取您希望 Airbyte 具有访问权限的数据的权限。请参阅 Salesforce 的文档,了解有关权限集的更多信息。如果您想同步 Salesforce 中的权限数据,您还需要 同步安全相关数据所需的权限

使用管理员帐户登录 Salesforce

步骤 1:创建新用户

  1. 在屏幕右上角,单击齿轮图标,然后单击 设置
  2. 在左侧导航栏中,在“管理”下,单击 用户 > 用户。创建新用户,输入用户的名字、姓氏、别名和电子邮件。填写电子邮件字段会自动填充用户名和昵称字段。
    1. 角色 留空
    2. 为用户许可证选择 Salesforce
    3. 为配置文件选择 标准用户
    4. 决定是否生成新密码并通知用户。
    5. 选择 保存

步骤 2:创建新的权限集

  1. 使用左侧导航栏,选择 用户 > 权限集
  2. 单击 新建 以创建新的权限集。
  3. 为您的权限集提供一个描述性的标签名称(例如,“Airbyte 只读访问权限”)。API 名称将根据您为权限集提供的标签自动填充。
  4. 对于许可证,将其保留为 –无—,然后单击 保存
  5. 现在您看到权限集已创建,可以通过对象设置定义权限。
    1. 单击“对象设置”。
    2. 选择您希望用户具有只读访问权限的每个对象的 对象名称(例如,帐户、联系人、商机)。
    3. 选择“编辑”,并选中“读取”权限,并清除所有其他权限(创建、编辑、删除等)
    4. 单击 保存
    5. 继续为任何您希望 Airbyte 具有访问权限的对象添加读取权限。
  6. 要授予对未安装的连接应用程序的访问权限,您需要启用其他权限。
    1. 单击“系统权限”
    2. 选择“编辑”
    3. 如果启用了 API 访问控制,则需要选中“使用任何 API 客户端”权限。如果未启用 API 访问控制,则需要选中“批准未安装的连接应用程序”权限。
    4. 单击 保存

步骤 3:将权限集分配给新用户

  1. 从权限集页面,单击您刚刚创建的只读权限集旁边的“管理分配”。
  2. 单击“添加分配”。
  3. 找到并选择您在步骤 1 中创建的用户。
  4. 单击 分配

登录到您上面使用的电子邮件,并验证您的新 Salesforce 帐户用户。您需要设置密码作为此过程的一部分。请将此密码保留在可访问的位置。

信息

配置文件与权限集:请记住,用户的配置文件提供他们的基本权限。权限集会在其之上添加或限制权限。对象级别与字段级别安全性:本指南侧重于对象级别的只读访问权限。在设置权限集时,您可以坚持对象级别的安全性,或者通过在每个对象设置页面向下滚动来选择仅对所需字段的读取访问权限来定义更精细的控制。

获取 Salesforce OAuth 凭据(仅限 Airbyte 开源版)

如果您使用的是 Airbyte 开源版,请获取以下 OAuth 凭据进行身份验证

  • 客户端 ID
  • 客户端密钥
  • 刷新令牌

要获取这些凭据,请按照 此演练 进行以下修改

  1. 如果您的 Salesforce URL 不是 X.salesforce.com 格式,请使用您的 Salesforce 域名。例如,如果您的 Salesforce URL 是 awesomecompany.force.com,则使用它而不是 awesomecompany.salesforce.com
  2. 运行 curl 命令时,使用 -L 选项以跟踪任何重定向。
  3. 如果您创建了只读用户,请在使用该用户凭据登录时生成 OAuth 令牌。

在 Airbyte 中设置 Salesforce 连接器

对于 Airbyte Cloud:

  1. 登录到您的 Airbyte Cloud 账户。
  2. 点击“来源”,然后点击“+ 新来源”。
  3. 在设置来源页面上,从来源类型下拉菜单中选择 Salesforce。
  4. 输入 Salesforce 连接器的名称。
  5. 要进行身份验证:对于 Airbyte Cloud:单击 授权您的帐户 以授权您的 Salesforce 帐户。Airbyte 将验证您已登录的 Salesforce 帐户。请确保您已登录到正确的帐户。
  6. 切换您的 Salesforce 帐户是否为 Sandbox 帐户 或生产帐户。
  7. (可选)对于 开始日期,使用提供的日期选择器或以 YYYY-MM-DDYYYY-MM-DDTHH:MM:SSZ 格式以编程方式输入日期。在此日期之后添加的数据将被复制。如果此字段留空,Airbyte 将默认复制过去两年的数据。请注意,时间戳采用 UTC
  8. (可选)在 筛选 Salesforce 对象 部分,您可以选择针对复制的目标特定数据。为此,单击 添加,然后在 搜索条件 下拉菜单中选择相关条件。对于 搜索值,添加相关的搜索词。您可以添加多个过滤器。如果未指定任何过滤器,Airbyte 将复制所有数据。
  9. 点击 Set up source 并等待测试完成。

对于 Airbyte 开源:

  1. 导航到 Airbyte 开源仪表板。
  2. 在左侧导航栏中,单击 来源。在右上角,单击 + 新增来源
  3. 从可用来源列表中找到并选择 Salesforce
  4. 输入您选择的 来源名称,以帮助您识别此来源。
  5. 要进行身份验证:对于 Airbyte 开源版:输入您的客户端 ID、客户端密钥和刷新令牌。
  6. 切换您的 Salesforce 帐户是否为 Sandbox 帐户 或生产帐户。
  7. (可选)对于 开始日期,使用提供的日期选择器或以 YYYY-MM-DDYYYY-MM-DDTHH:MM:SSZ 格式以编程方式输入日期。在此日期之后添加的数据将被复制。如果此字段留空,Airbyte 将默认复制过去两年的数据。请注意,时间戳采用 UTC
  8. (可选)在 筛选 Salesforce 对象 部分,您可以选择针对复制的目标特定数据。为此,单击 添加,然后在 搜索条件 下拉菜单中选择相关条件。对于 搜索值,添加相关的搜索词。您可以添加多个过滤器。如果未指定任何过滤器,Airbyte 将复制所有数据。
  9. 点击 Set up source 并等待测试完成。

支持的同步模式

Salesforce 源连接器支持以下 同步模式

支持的流

Salesforce 连接器支持读取 Salesforce 中的标准对象和自定义对象。每个对象都作为单独的数据流读取。请在此处查看所有 Salesforce 标准对象的列表 此处

Airbyte 允许根据以下条件动态导出所有可用的 Salesforce 对象

  • 如果经过身份验证的 Salesforce 用户具有读取和获取对象的角色和权限。这将在您分配给 Airbyte 用户的权限集中设置。有关更多信息,请参阅 创建专用的 Salesforce 用户
  • 如果 Salesforce 对象已将 queryable 属性设置为 true。Airbyte 只能获取可查询的对象。如果您看不到 Airbyte 可用的对象,并且它是可查询的,请检查它是否可供您进行身份验证的 Salesforce 用户访问。

从 Salesforce 同步权限数据

Salesforce 连接器可用于同步安全相关的对象,这些对象可以同步以了解 Salesforce 组织中的用户权限、角色和访问模式。

同步 Salesforce 权限数据的常见用例包括

  • 权限复制:利用 Salesforce 源中的权限来指导下游应用程序的权限应用。
  • 安全审计:生成有关用户访问权限和权限分配的报告。

以下数据流包含安全和权限相关的数据

  • User - 包含配置文件、角色和用户权限等安全相关字段的核心用户帐户。包含有关用户状态、登录历史记录和分配的许可证的信息。
  • ActivePermSetLicenseMetric - 跟踪权限集许可证使用情况指标,包括分配的用户数量、活动用户数量和可用总许可证数量。
  • ActiveProfileMetric - 提供有关用户配置文件使用情况的指标,包括用户许可证关联和分配计数。

有关 Salesforce 安全对象的全面信息,请参阅 Salesforce 对象参考文档。

Salesforce 权限同步的工作方式

Salesforce 通过其标准对象模型提供一些安全相关的数据

  1. 动态对象发现:连接器根据经过身份验证的用户的权限自动发现可用的 Salesforce 对象(sobjects)。
  2. 基于权限的访问:可用的安全对象取决于授予用于身份验证的 Salesforce 用户的权限以及您的 Salesforce 环境配置。
  3. 标准对象同步:可用的安全相关对象作为常规 Salesforce 对象通过与其它业务数据相同的同步机制同步。
注意

安全相关对象的可用性因 Salesforce 环境(生产环境与沙盒环境)和用户权限而异。安全对象可能是在拥有大量用户的组织中的大型数据集,因此请相应地监控您的 Salesforce API 限制。

同步权限数据所需的权限

要从 Salesforce 同步安全相关的数据,经过身份验证的 Salesforce 用户必须具有读取安全对象的适当权限。可以考虑通过专用的权限集授予这些权限

  • "查看所有用户" - 访问全面的用户数据所必需。
  • 您想要同步的特定对象的标准读取权限。

有关 Salesforce 安全和权限的更多信息,请参阅 Salesforce 官方文档中的 用户权限权限集

限制和故障排除

展开以查看有关 Salesforce 连接器限制和故障排除的详细信息。

连接器限制

速率限制

Salesforce 连接器受 Salesforce 的 每日速率限制的限制。连接器同步数据,直到达到每日速率限制,然后提前以成功状态结束同步,并从上次停止的地方开始下一次同步。请注意,仅当使用增量同步时,才能从上次停止的地方继续,这就是我们建议使用 增量同步 - 追加 + 去重同步模式的原因。

同步公式字段

Salesforce 连接器同步来自 Salesforce 的公式字段输出。如果 Salesforce 中字段的公式发生更改,并且记录上的其他字段未更新,则需要重置数据流并同步历史回填,以提取该字段的所有更新值。

同步删除

Salesforce 连接器支持从 Salesforce 回收站检索已删除的记录。对于支持它的数据流,已删除的记录将标记为 isDeleted=true。要了解有关 Salesforce 如何管理回收站中的记录的更多信息,请访问他们的 文档

使用 BULK API 与 REST API

Salesforce 允许使用 BULK APIREST API 提取数据。为了实现快速性能,Salesforce 建议使用 BULK API 提取大量数据(超过 2,000 条记录)。因此,Salesforce 连接器默认使用 BULK API 提取任何 Salesforce 对象,除非满足以下任何条件

  • Salesforce 对象具有 BULK API 不支持的列,例如具有 base64complexvalue 类型的列
  • Salesforce 对象不受 BULK API 支持。在这种情况下,我们通过 REST API 同步对象,这偶尔会花费更多的 API 配额。这包括以下对象
    • AcceptedEventRelation
    • Attachment
    • CaseStatus
    • ContractStatus
    • DeclinedEventRelation
    • FieldSecurityClassification
    • KnowledgeArticle
    • KnowledgeArticleVersion
    • KnowledgeArticleVersionHistory
    • KnowledgeArticleViewStat
    • KnowledgeArticleVoteStat
    • OrderStatus
    • PartnerRole
    • RecentlyViewed
    • ServiceAppointmentStatus
    • ShiftStatus
    • SolutionStatus
    • TaskPriority
    • TaskStatus
    • UndecidedEventRelation

有关各种 Salesforce API 之间差异的更多信息,请在此处查看 此处

强制使用 Bulk API

如果将 强制使用 Bulk API 选项设置为 true,连接器将忽略不受支持的属性并使用 BULK API 同步数据流。

参考

配置字段参考

字段
类型
属性名称
字符串
client_id
字符串
client_secret
字符串
refresh_token
auth_type
"Client"
auth_type
布尔值
force_use_bulk_api
布尔值
is_sandbox
字符串
start_date
字符串
stream_slice_step
array<object>
streams_criteria

变更日志

展开以查看
版本日期拉取请求主题
2.7.162025-10-2969078将发布候选版本 2.7.16-rc.1 提升到主版本。
2.7.16-rc.12025-10-2766136微小的性能调整
2.7.152025-10-2268166ActivityFieldHistory 添加到 UNSUPPORTED_FILTERING_STREAMS 以修复丢失的记录
2.7.142025-10-2168455更新依赖项
2.7.132025-10-1460432更新依赖项
2.7.122025-09-1566136更新到 CDK v7
2.7.112025-05-1460271定义建议的数据流
2.7.102025-05-1060100更新依赖项
2.7.92025-05-0459644更新依赖项
2.7.82025-04-2758997更新依赖项
2.7.72025-04-1958453更新依赖项
2.7.62025-04-1257976更新依赖项
2.7.52025-04-0557424更新依赖项
2.7.42025-03-2753689捕获错误响应的 JSONDecodeError
2.7.32025-03-2956776更新依赖项
2.7.22025-03-2455898修复输入状态序列化问题
2.7.12025-03-2251921更新依赖项
2.7.02025-03-2055186更新清单以适应 AsyncRetriever 的更改
2.6.52025-02-2054178将发布候选版本 2.6.5-rc.1 提升到主版本。
2.6.52025-02-2054178将发布候选版本 2.6.5-rc.1 提升到主版本。
2.6.5-rc.12025-02-1853229升级到 API v62.0
2.6.42025-01-1148635从这个版本开始,Docker 镜像现在是 rootless。 请注意,此版本和未来的版本将与 Airbyte 版本早于 0.64 不兼容
2.6.32024-11-0546835更新依赖项
2.6.22024-10-10将 CDK 的最低版本提高到 5.10.2
2.6.12024-10-0546436更新依赖项,包括 v5.10.2 中的 CDK 修复
2.6.02024-10-0245678让 bulk 数据流使用 CDK 组件
2.5.342024-09-2846187更新依赖项
2.5.332024-09-2145779更新依赖项
2.5.322024-09-1445579更新依赖项
2.5.312024-09-0745329更新依赖项
2.5.302024-08-3144959更新依赖项
2.5.292024-08-2444747更新依赖项
2.5.282024-08-1744327更新依赖项
2.5.272024-08-1243732更新依赖项
2.5.262024-08-1043673更新依赖项
2.5.252024-08-0343211更新依赖项
2.5.242024-07-2742685更新依赖项
2.5.232024-07-2042166更新依赖项
2.5.222024-07-1341752更新依赖项
2.5.212024-07-1041529更新依赖项
2.5.202024-07-0941255更新依赖项
2.5.192024-07-0841043使用尽可能最新的 CDK 版本
2.5.182024-07-0640835更新依赖项
2.5.172024-06-2540329更新依赖项
2.5.162024-06-2139927更新依赖项
2.5.152024-06-1639517Salesforce 重构:添加 CheckpointMixin 用于状态管理
2.5.142024-06-0639269[autopull]将基础镜像升级到 v1.2.2
2.5.132024-05-2338563使用 HttpClient 执行 bulk、身份验证和模式发现的 HTTP 请求
2.5.122024-05-1638255将 AirbyteLogger 替换为 logging.Logger
2.5.112024-05-0938205在 test_bulk_stream 中使用新的 delete 方法的 HttpMocker
2.5.102024-05-0938065替换过时的身份验证机制为最新的机制
2.5.92024-05-0237749为 bulk 数据流添加模拟服务器测试
2.5.82024-04-3037340源 Salesforce:减少信息日志
2.5.72024-04-2436657模式描述
2.5.62024-04-1937448确保并发 CDK 中的 AirbyteTracedException 以正确的类型发出
2.5.52024-04-1837419确保在发生错误时 python 返回代码 != 0
2.5.42024-04-1837392更新 CDK 版本以修复分区状态
2.5.32024-04-1737376改进检查命令期间的速率限制错误消息
2.5.22024-04-1537105在模式生成失败时引发错误
2.5.12024-04-1137001更新 airbyte-cdk 以刷新每次消息的打印缓冲区
2.5.02024-04-1136942将 Salesforce 移动到分区状态,以避免卡住的同步
2.4.42024-04-0836901升级 CDK 以使 internal_message 在引发 ExceptionWithDisplayMessage 时为空
2.4.32024-04-0836885为 REST API 添加重试
2.4.22024-04-0536862升级 CDK 以更新有关缺少数据流的错误消息
2.4.12024-04-0336385在各种情况下重试 HTTP 请求和作业
2.4.02024-03-1235978升级 CDK 以开始发出带有状态和完全刷新状态的记录计数
2.3.32024-03-0435791修复内存泄漏(OOM)
2.3.22024-02-1935421在规范中添加数据流切片步长选项
2.3.12024-02-1235147使用 Poetry 管理依赖项。
2.3.02023-12-1533522在所有同步模式下并发同步数据流
2.2.22024-01-0433936为 airbyte-lib 准备
2.2.12023-12-1233342添加新的 ContentDocumentLink 数据流
2.2.02023-12-1233350在完全刷新时并发同步数据流
2.1.62023-11-2832535并发运行完全刷新同步
2.1.52023-10-1831543基础镜像迁移:移除 Dockerfile 并使用 python-connector-base 镜像
2.1.42023-08-1729538修复编码猜测
2.1.32023-08-1729500处理过期的刷新令牌错误
2.1.22023-08-1028781修复 BULK API 作业的分页;添加强制使用 BULK API 的选项
2.1.12023-07-0628021修复多个漏洞;切换到使用 alpine 代替 slim,CVE-2022-40897, CVE-2023-29383, CVE-2023-31484, CVE-2016-2781
2.1.02023-06-2627726许可证更新:Elv2
2.0.142023-05-0425794强制所有数据类型为对象,避免 pandas 推断错误的数据类型
2.0.132023-04-3025700移除分页和查询限制
2.0.122023-04-2525507更新 API 版本至 57
2.0.112023-04-2025352更新 API 版本至 53
2.0.102023-04-0524888添加更频繁的检查点
2.0.92023-03-2924660如果配置中未提供 start_date,则默认同步最近两年
2.0.82023-03-3024690处理批量操作的速率限制
2.0.72023-03-1424071移除 start_date 的正则表达式,改为使用格式验证
2.0.62023-03-0322891在规范中指定日期格式
2.0.52023-03-0123610处理不同查询的不同 Salesforce 页面大小
2.0.42023-02-2422636为所有非 BulkSalesforceStream 类的流开启默认 HttpAvailabilityStrategy
2.0.32023-02-1723190如果属性被分块,则在每个块中获取主键
2.0.22023-02-1322896根据编码后的参数计算 URL 长度
2.0.12023-02-0822597如果 REST 流具有过多的属性,则发出多个请求
2.0.02023-02-0222322移除 ActivityMetricRollup
1.0.302023-01-2722016为流显式设置为 NoneAvailabilityStrategy
1.0.292023-01-0520886移除 ActivityMetric
1.0.282022-12-2920927修复测试;添加预期的记录
1.0.272022-11-2919869从不支持的 BULK 流中移除 AccountHistory
1.0.262022-11-1519286错误修复:如果实体不受 BULK API 支持,则回退到 REST API
1.0.252022-11-1319294为非 UTF-8 对象和数据使用正确的编码
1.0.242022-11-0118799更新不受支持的 Bulk API 对象列表
1.0.232022-11-0118753为 ConnectionError 添加 error_display_message
1.0.222022-10-1217615如果 cursor_field 在一个页面内没有改变,则使分页工作
1.0.212022-10-1017778EventWhoRelation 添加到不受支持的 Bulk API 对象列表中。
1.0.202022-09-3017453检查 Bulk API (v52.0) 不支持的对象
1.0.192022-09-2917314修复响应解码错误
1.0.182022-09-2817304迁移到每个流的状态。
1.0.172022-09-2317094调整连接检查:获取可用流的列表
1.0.162022-09-2117001改进解码文件的写入
1.0.152022-08-3016086改进 API 类型检测
1.0.142022-08-2916119排除 KnowledgeArticleVersion 使用 bulk API
1.0.132022-08-2315901排除 KnowledgeArticle 使用 bulk API
1.0.122022-08-0915444修复当 Bulk Job 被连接器超时,但仍在服务器上运行时的问题
1.0.112022-07-0713729改进配置字段描述
1.0.102022-06-0913658修正同步大于页面大小的流的逻辑
1.0.92022-05-0612685将 CDK 更新到 v0.1.56,以便在出现未捕获异常时发出 AirbyeTraceMessage
1.0.82022-05-0412576将响应解码为 utf-8,并在需要时回退到 ISO-8859-1
1.0.72022-05-0312552将响应解码为 ISO-8859-1,而不是 utf-8
1.0.62022-04-2712335为显式休眠的连接器添加固定程序以模拟 time.sleep
1.0.52022-04-2512304添加 Describe
1.0.42022-04-2012230更新连接器以使用 spec.yaml
1.0.32022-04-0411692优化 BULK API 调用的内存使用
1.0.22022-03-0110751修复连接器配置中的损坏的链接锚点
1.0.12022-02-2710679重新组织 UI 上的输入参数顺序
1.0.02022-02-2710516通过使用并行性来加速模式发现
0.1.232022-02-1010141处理失败的作业
0.1.222022-02-0210012增加 CSV field_size_limit
0.1.212022-01-289499如果同步达到每日速率限制,则提前以成功状态结束同步。更多信息请参阅 Performance considerations 部分
0.1.202022-01-269757使用 "unix" 方言解析 CSV
0.1.192022-01-258617更新连接器字段标题/描述
0.1.182022-01-209478添加按 queryable 标志过滤可用流的功能
0.1.172022-01-199302弃用 API 类型参数
0.1.162022-01-189151修复 REST API 流中的分页
0.1.152022-01-119409修正错误处理中多余的 else 处理程序的出现
0.1.142022-01-119386处理 400 错误,当 sobject 不支持 queryqueryAll 请求时
0.1.132022-01-118797在规范中从 authSpecification 切换到 advanced_auth
0.1.122021-12-238871修复规范中新字段的 examples
0.1.112021-12-238871添加按用户过滤流的功能
0.1.102021-12-239005处理当流不可查询时出现的 400 错误
0.1.92021-12-078405过滤 HTTP 响应中的 'null' 字节
0.1.82021-11-308191使 start_date 可选,并将其格式更改为 YYYY-MM-DD
0.1.72021-11-248206处理尝试为使用 Bulk API 同步创建作业时出现的 400 错误。
0.1.62021-11-168009修复 BULK 作业的重试
0.1.52021-11-157885为输出记录添加 Transform
0.1.42021-11-097778修复 anyType 字段的类型
0.1.32021-11-067592修复使用 BULK API 获取 anyType 字段的问题
0.1.22021-09-306438注释连接器规范中的 Oauth2 流程初始化参数
0.1.12021-09-216209修复 BULK API 的分页错误
0.1.02021-09-085619Salesforce Aitbyte-Native 连接器