Salesforce 触发器

公告：Application Integration 现在可供您的 Google Cloud 项目使用。现在，您可以在同一 Google Cloud 项目中同时使用 Apigee Integration 和 Application Integration 了。了解详情

借助 Salesforce 触发器，您可以监听变更数据捕获 (CDC) 事件或企业消息传递平台事件。使用此触发器，您可以根据 Salesforce 实例中的任何 CDC 事件（Create、Update、Delete 或 Undelete）或平台事件来启动集成。

准备工作

本部分概述了连接和配置 Salesforce 实例以使用变更数据捕获 (CDC) 或平台事件以发布/订阅方式将变更流式传输到您的 Apigee Integration 所需的步骤。在 Apigee 中配置任何与 Salesforce 相关的任务或触发器之前，必须完成以下步骤：

• 设置集成用户
• 配置权限集
• 设置安全令牌
• 创建关联的应用

注意：如需完成这些步骤，您需要具备对 Salesforce 实例的系统管理员权限。如果您没有管理员访问权限，请与您的 Salesforce 管理员共享这些说明。

本教程提供深入说明，但我们建议您对 Salesforce 配置选项有一定了解。Salesforce 提供详细的开发者文档，可帮助您上手使用。

设置集成用户

注意：如果您已有集成用户并且知道密码，则可以跳到下一步。如果您需要重置密码，请参阅下文中的第 6 步。

按照以下步骤设置集成用户：

1. 使用您的 sysadmin 凭据登录您的 Salesforce 实例。
2. 点击齿轮图标，然后选择 Setup，如下图所示：
3. 在 Administration 菜单中，点击 Users > Users。
4. 在 Users 窗格中，选择 New User 按钮。
5. 在 User Edit 对话框中，填写以下详细信息：
   1. First Name：集成用户的名字。
   2. Last Name：集成用户的姓氏。
   3. Email Address：集成用户的电子邮件地址。最好是群组电子邮件地址。
   4. Username：符合任何组织级命名规则的用户名。

      如果您要创建新的集成用户，请使用以下格式：EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      如果您已有集成用户，请确认已在此处输入用户名。

   5. Role：从选项下拉菜单中选择。
   6. User License：输入 Salesforce；如果使用试用组织，则输入 Salesforce Platform。
   7. Profile：从下拉菜单中选择集成用户的权限配置文件。

      我们建议不向配置文件分配任何权限，以防止集成用户 Salesforce 访问权限被未经授权地使用。

   8. 点击保存。
6. 如需更新新集成用户的密码，请按以下步骤操作：
   1. 点击 Users 窗格中的 Reset password(s)。系统会将一封重置密码电子邮件发送到与该用户关联的电子邮件地址。
      注意：在触发重置密码流程之前，请确认您可以访问与该集成用户关联的电子邮件账号。此外，如果您已为此用户启用了 SSO，则无法重置密码。如需启用重置选项，请转到 Profile > System Permissions，然后取消选中 SSO Login Enabled 选项。
   2. 按照电子邮件账号中的重置密码流程操作。记下新密码，因为您将在后续步骤中用到它。

配置权限集

如果您已有适合集成用户的权限集，则可以跳过此步骤并转到设置安全令牌步骤。否则，请按照以下步骤为集成用户和 Salesforce 对象配置权限集。

如需为集成用户配置权限集，请执行以下操作：

1. 在 Setup 菜单中，点击 Users > Permission Sets。
2. 在 Permission Sets 窗格中，点击 New 按钮。
3. 在 Permission Sets 对话框中，输入以下详细信息：
   • Label：输入权限集的名称。
   • License：从 License 下拉菜单中选择 Salesforce。
   • 点击保存。
4. 在 System 设置选项列表中，向下滚动并选择 System Permissions。
5. 在 System Permissions 页面上，点击 Edit 按钮。
6. 向下滚动可用权限列表，并选中 API Enabled 复选框。

   Api Only User 权限也是必需的，但在所需的安全令牌重置之前无法启用该权限。此权限将在后续步骤中添加。

7. （可选）滚动并选中 Modify All Data 和 View All Data。这些权限不是必需的，但如果您希望自动向集成用户授予新对象的访问权限，则这些权限很有用。我们建议您仅在沙盒中启用这些权限用于测试。
8. 滚动到权限列表的顶部，然后点击 Save。
9. 确认设置，然后点击 Save。

要为 Salesforce 对象配置权限集，请执行以下操作：

1. 点击 Permission Set Overview 以返回主 Permissions Set 配置页面。
2. 在 Permissions Set 窗格的 Apps 部分，选择 Object Settings。
3. 向下滚动并选择需要权限集的 Salesforce 对象。本示例使用 Opportunity 对象。
   注意：CDC 仅支持一部分标准 Salesforce 对象。如需了解详情，请参阅更改事件对象支持。
4. 点击对象详情页面上的 Edit 按钮。
5. 选中记录类型的复选框。如果您知道哪些记录类型是必需的，请选择相应的记录类型。如果您不知道哪些记录类型是必需的，请选择所有记录类型。
6. 选中要启用的 Object Permissions 对应的复选框。建议选择 Read 和 View All。
7. 通过选中 Read Access 或 Edit Access 复选框，为每个对象字段授予相应的权限。
   注意：使用 CDC 时不需要写入权限。
8. 滚动到页面顶部，然后点击 Save。

设置安全令牌

如果您之前已经为集成用户创建了安全令牌并重置了密码，系统会自动发送包含新安全令牌的电子邮件。您可以使用新令牌并跳至创建关联的应用。

否则，请按照以下步骤重置集成用户的安全令牌：

1. 使用上一步中设置的用户名和密码，以集成用户的身份登录 Salesforce。
2. 在主菜单中点击配置文件图片，然后点击 Settings。
3. 在 Settings 菜单中，选择 Reset My Security Token 以打开 Reset Security Token 窗格。
4. 点击 Reset Security Token 按钮。
5. 查看与该集成用户关联的电子邮件账号，寻找包含新的安全令牌的电子邮件。记下新的安全令牌，因为您将在后续步骤中用到它。
6. （可选）为您的权限集启用 System Permissions 中的 Api User Only 权限，如上文的配置权限集步骤所述。

创建关联的应用

您必须拥有系统管理权限才能设置关联的应用。如果您目前以集成用户身份登录，请务必退出并以 sysadmin 身份重新登录。

按照以下步骤设置关联的应用：

1. 点击齿轮图标，然后选择 Setup。
2. 在 Setup 菜单中，搜索并选择 App Manager，如下图所示：
3. 点击 New Connected App。
4. 在配置窗格中，提供以下详细信息：
   • Connected App Name：输入关联的应用的名称。
   • API Name：输入 API 的名称。
   • Contact email：输入关联的应用的电子邮件地址，最好是群组电子邮件别名。
   • API (Enable OAuth Settings)：选择 Enable OAuth Settings。然后设置以下各项：
     1. （可选）Callback URL：仅当您希望外部服务执行验证时，才需要设置此项。如果您选择提供回调，请确保添加 http(s):// 前缀。
     2. Selected OAuth Scopes：选择：
        • Access and manage your data (api)
        • Perform requests on your behalf at any time (refresh_token, offline_access)
5. 点击保存。
   注意：新创建的关联应用在创建后的最初 2-10 分钟内将无法正常运行。
6. 点击继续。您需要使用发送到您的电子邮件地址的验证码重新授权。
7. 成功验证该验证码后，下一页上会显示使用方密文和使用方密钥。请记下这些值，因为在设置 Apigee 的身份验证模块时会用到它们。
8. 点击管理按钮。
9. 进入 Connected App Detail 页面后，点击 Edit Policies 按钮。
10. 在 OAuth Policies 部分，将 Permitted Users 下拉菜单中的值更改为 Admin approved users are pre-authorized。
11. 点击保存。
12. 滚动到页面的 Profiles 和 Permission Sets 部分，选择要应用于关联应用的配置文件或权限集。
    您可以选择配置文件和/或权限集，这将允许拥有正确配置文件或权限集的用户访问关联的应用。
13. 选择所需的配置文件或权限集。
14. 点击保存。

使用 CDC 事件的前提条件步骤

在配置您的 Apigee 触发器以使用 CDC 事件之前，请确保将配置的对象添加到 Salesforce 中的 CDC：

1. 以 sysadmin 身份登录 Salesforce。
2. 点击齿轮图标，然后点击 Setup。
3. 使用左侧导航栏搜索并选择 Change Data Capture。
4. 在 Change Data Capture 设置页面上，在 Available Entities 列中找到要使用的 Salesforce 对象，并将其拖到 Selected Entities 列。
   注意：对于 CDC，每个 Salesforce 许可最多可以选择 5 个对象。请与您的 Salesforce 代表联系，了解详细信息和许可选项。
5. 点击保存。

使用平台事件的前提条件步骤

在配置您的 Apigee 触发器以使用平台事件之前，请在 Salesforce 中完成以下步骤：

• 创建平台事件
• 更新平台事件的权限

创建平台事件

如需创建平台事件，请执行以下步骤：

1. 使用您的 sysadmin 凭据登录您的 Salesforce 实例。
2. 点击齿轮图标，然后选择设置。
3. 在导航窗格中，搜索平台，然后点击平台事件。

4. 在平台事件页面中，点击新建平台事件并设置以下属性：

• 标签
• 复数标签 (Plural Label)
• 对象名称（此字段自动填充）
• 发布行为 (Publish Behavior) 选择以下任一值：
  • 提交后发布 (Publish After Commit)：如果不满足条件，则还原事件流式传输。
  • 立即发布 (Publish Immediately)：立即触发事件，不等待任何验证。
  如需详细了解发布行为，请参阅平台事件和事务。
• 部署状态（可选）：如果事件已准备好进行部署，请选择已部署。

点击保存。

创建自定义字段。如需创建自定义字段，请点击“自定义字段和关系”部分中的新建，然后选择自定义字段类型。您可以根据需要创建任意数量的自定义字段。

创建自定义字段后，请注意平台事件页面中的 API 名称字段的值。对象名称以 _e 结尾，这表示对象是平台事件对象。对于 CDC 对象，对象名称以 _c 结尾。

更新平台事件的权限

必须更新权限集，才能允许集成用户访问新创建的平台事件。

如需更新权限，请执行以下步骤：

1. 在 Setup 菜单中，点击 Users > Permission Sets。
2. 在权限集 (Permission Sets) 页面中，点击之前创建的权限。
3. 点击对象设置 (Object Settings) > Plural Label of the Platform Event。
4. 在对象权限部分，启用读取和创建权限。
5. 点击保存。

添加 Salesforce 触发器

如需将 Salesforce 触发器添加到新的或现有的集成中，请按以下步骤操作：

1. 在 Apigee 界面中，选择您的 Apigee 组织。
2. 点击开发 > 集成。
3. 选择现有集成，或通过点击创建集成来创建新集成。

   要创建新的集成，请执行以下操作：

   1. 在创建 Integrations对话框中输入名称和说明。
   2. 从支持的区域列表中选择集成的区域。
   3. 点击创建。

   这将在集成设计器中打开集成。

4. 在集成设计器导航栏中，点击 + 添加任务/触发器 > 任务以查看可用任务列表。
5. 选择现有集成或点击创建集成。
6. 在集成编辑器中，点击 + 添加任务/触发器 > 触发器以查看可用的触发器
7. 点击 Salesforce 触发器元素并将其放入设计器。

配置 Salesforce 触发器

如需配置 Salesforce 触发器，请执行以下步骤：

1. 点击集成编辑器中的 Salesforce 触发器以查看触发器配置窗格。
2. 从 Salesforce 实例配置 (Salesforce instance configuration) 下拉列表中选择 Salesforce 实例。

   如果您没有 Salesforce 实例，请创建一个新实例。如需了解详情，请参阅创建新的 Salesforce 实例。

3. 从 Salesforce 渠道配置 (Salesforce channel configuration) 下拉列表中选择 Salesforce 渠道。

   如果您没有 Salesforce 渠道，请创建一个新渠道。如需了解详情，请参阅创建新的 Salesforce 渠道。

4. 如果您选择了 CDC 事件类型，请选择以下任一操作：
   • Create
   • Update
   • Delete
   • Undelete

   触发器仅在特定操作或间隔操作发生时才运行。

   只能为一个操作配置 Salesforce 触发器。如果要为多个操作运行触发器，请为每个操作创建一个 Salesforce 触发器。

创建新的 Salesforce 实例

如需配置新的 Salesforce 实例，请执行以下步骤：

1. 在触发器的可修改属性中，点击选择 Salesforce 实例配置 (Select a Salesforce instance configuration) > + 添加新的 Salesforce 实例配置 (Add new Salesforce instance configuration)。
2. 在添加 Salesforce 实例配置对话框中，设置以下属性：
• Salesforce 实例连接名称 (Salesforce instance connection name)：输入实例的名称。

  配置完成后，您将使用此名称来引用 Salesforce 实例。

• Salesforce 网域：输入实例的服务授权方。您可以在 Salesforce 账号中找到该网域。例如 instance.my.salesforce.com。下图显示了 Salesforce 网域：

  

• 身份验证配置文件：选择身份验证配置文件。

  如果您没有身份验证配置文件，请创建 OAuth 2.0 资源所有者密码凭据身份验证类型的新配置文件。下图展示了创建身份验证配置文件所需的字段：

  

  如需了解这些字段，请参阅 OAuth 2.0 资源所有者密码凭据。对于 Salesforce 实例，请输入以下值：
  • 客户端 ID：输入您在设置关联的应用时记下的使用方密钥。
  • 密文：输入您在设置关联的应用时记下的使用方密文。
  • 密码：使用 USER_PASSWORDSECURITY_TOKEN 格式输入用户密码。替换以下内容：
    • USER_PASSWORD：Salesforce 用户密码。
    • SECURITY_TOKEN：您为集成设置的安全令牌。
    例如，如果 USER_PASSWORD 为 test-password，SECURITY_TOKEN 为 737K27NCa3O6，则密码将为 test-password737K27NCa3O6。

Salesforce 组织 ID：输入 Salesforce 实例的组织 ID。您可以从 Salesforce 管理员处获取该 ID。

点击添加。

创建新的 Salesforce 渠道

如需配置新的 Salesforce 渠道，请执行以下步骤：

1. 在触发器的可修改属性中，点击选择 Salesforce 渠道配置 (Select a Salesforce channel configuration) > + 添加新的 Salesforce 渠道配置 (Add new Salesforce channel configuration)。
2. 在添加 Salesforce 渠道配置 (Add Salesforce channel configuration) 对话框中，输入 Salesforce 对象名称 (Salesforce object name) 属性的对象名称。

   如果您不确定对象名称，请与您的 Salesforce 管理员联系。

3. 点击添加。

输出变量

您可以在输出变量中找到 Salesforce 触发器的响应。

下表介绍了 CDC 事件的输出变量：

变量	数据类型	说明
SalesforceTriggerCdcPayload	JSON	更改事件的详细信息。
SalesforceTriggerEvent	JSON	包含事件的 replayId。
SalesforceTriggerSchema	字符串	触发器架构。
SalesforceTriggerCdcSnapshot	JSON	更改事件发生后对象的快照。此字段仅适用于 Update 和 Create 操作。
SalesforceTriggerCdcRecordId	字符串	包含已更新或已添加记录的 recordId。recordId 是已更改的 Salesforce 对象的标识符。

下表介绍了平台事件的输出变量：

变量	数据类型	说明
SalesforceTriggerPEPayload	JSON	更改事件的详细信息。
SalesforceTriggerEvent	JSON	包含事件的 replayId。
SalesforceTriggerSchema	字符串	触发器架构。

此触发器的输出参数是 CdcTriggerPayload JSON 变量。JSON 变量包含更新后的记录对象。

最佳做法

如果您想使用 Salesforce 通知来触发集成，而无需编写自定义代码来发布 Salesforce 事件，建议使用 Salesforce 触发器。 Salesforce 案例中的任何微小更改都会触发 Salesforce CDC 事件，从而触发集成，这会导致明显的集成噪声。请考虑使用更改事件过滤条件，以仅过滤触发集成所需的 CDC 事件。使用更改事件过滤条件有助于减少集成噪声并确保符合许可限制。

同样，当不再需要集成时，我们建议使用此触发器取消发布集成。集成将持续侦听 Salesforce CDC 和平台事件，直到取消发布或删除为止。

注意事项

在使用 Salesforce 触发器运行集成之前，请考虑以下事项：

• 通常，Salesforce 每天最多可以发送 10 万个 CDC 和平台事件。在为集成触发器选择 CDC 事件之前，请与您的 Salesforce 管理员联系以了解许可限制。
  注意：多个集成使用同一 Salesforce 渠道不会使 Salesforce 配额消耗加倍。
• 如果您打算批量上传到 Salesforce，请考虑暂停 CDC，以减少集成噪音并确保符合许可限制。
• Salesforce 可以发布的事件消息大小上限为 1 MB。如需了解详情，请参阅变更数据捕获分配。
• Apigee 不支持以下 minicluster 区域的 Salesforce CDC 事件：
  • asia-northeast1
  • asia-south1
  • australia-southeast1
  • europe-west2
  • europe-west3
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-east4
  • us-west2