Salesforce 咨询顾问指南：利用 External Services 实现声明式 API 集成

背景与应用场景

作为一名 Salesforce 咨询顾问，我经常遇到客户提出各种各样的集成需求。他们希望 Salesforce 不再是一个信息孤岛，而是能与企业的核心系统（如 ERP、物流、财务软件等）进行实时数据交互。传统的解决方案通常依赖于 Salesforce 开发人员编写复杂的 Apex Callouts，这不仅开发周期长、成本高，而且后续的维护和迭代也需要专业的开发资源。这对于希望快速响应业务变化、并充分利用现有管理员团队的企业来说，无疑是一个痛点。

正是在这样的背景下，Salesforce External Services (外部服务) 应运而生。它是一个革命性的声明式集成工具，允许 Salesforce 管理员和顾问在无需编写一行代码的情况下，将外部的 REST API 集成到 Salesforce 平台中。这极大地降低了集成的技术门槛，赋予了业务分析师和管理员直接构建强大集成的能力。

以下是一些典型的应用场景：

1. 实时物流状态查询

场景：一家电商企业的客服人员在处理客户的售后工单 (Case) 时，需要频繁查询订单的实时物流状态。物流信息存储在第三方的物流供应商系统中。

解决方案：通过 External Services 注册物流供应商提供的物流查询 API。然后，在 Flow 中创建一个屏幕流 (Screen Flow)，客服人员只需在工单页面输入运单号，Flow 就会调用外部 API，并将返回的物流状态、当前位置、预计送达时间等信息实时显示在屏幕上，极大地提升了客服效率和客户满意度。

2. 外部信用评级调用

场景：一家金融机构在审批贷款申请 (Opportunity) 时，需要从外部信用评级机构获取申请人的信用分数。

解决方案：将信用评级机构的 API 注册为 External Service。创建一个由 Opportunity 记录触发的 Flow，当商机阶段变为“提交审批”时，Flow 自动将申请人的信息发送到外部 API，获取信用分数后，再将分数回写到 Opportunity 的指定字段上，并根据分数高低自动更新审批状态或通知相关人员。

3. 动态货币汇率转换

场景：一家跨国公司的销售团队在创建报价 (Quote) 时，需要使用最新的货币汇率将美元报价转换为客户当地的货币。

解决方案：利用一个提供实时汇率的公共 API，通过 External Services 将其集成。在报价页面创建一个快速操作 (Quick Action) 按钮，点击后触发一个 Flow。该 Flow 调用汇率 API，获取美元与目标货币的最新汇率，并自动计算和更新报价上的金额，确保报价的准确性。

---

原理说明

External Services 的核心原理是将一个描述 REST API 结构的标准化规范文件，转换为 Salesforce 平台内可直接使用的可调用操作 (Invocable Action)。这个过程完全是自动化的，背后隐藏了复杂的代码生成和调用逻辑。

其工作流程可以分解为以下几个步骤：

1. API 规范 (API Specification)

一切的起点是一份有效的 API 规范文件。External Services 主要支持 OpenAPI（以前称为 Swagger）格式，特别是 OpenAPI 2.0 (JSON 或 YAML) 和 OpenAPI 3.0 (JSON 或 YAML)。这份文件就像一份 API 的“说明书”，它用标准化的方式详细定义了 API 的所有信息，包括：

• Endpoints: 可用的 URL 路径，例如 /users/{userId}。
• Operations: 每个路径支持的 HTTP 方法，如 GET, POST, PUT, DELETE。
• Parameters: 调用每个操作时需要传入的参数，包括其名称、类型（字符串、数字等）、位置（路径、查询、请求体等）和是否必需。
• Request/Response Bodies: 请求和响应的数据结构（Schema），即 JSON 或 XML 的格式。

2. 注册与生成 (Registration and Generation)

Salesforce 管理员通过 `设置 > 集成 > 外部服务` 菜单，将这份 OpenAPI 规范文件注册到 Salesforce 中。在注册过程中，Salesforce 会解析这份规范文件。对于规范中定义的每一个 Operation，Salesforce 都会在后台自动生成一个对应的 Invocable Action。

例如，如果 OpenAPI 规范中定义了一个名为 `getUser` 的 GET /users/{userId} 操作，它需要一个名为 `userId` 的路径参数，并返回一个包含 `firstName` 和 `lastName` 字段的用户对象。注册后，Salesforce 会生成一个名为 `getUser` 的可调用操作。这个操作会有一个名为 `userId` 的输入参数，以及一个包含 `firstName` 和 `lastName` 属性的输出对象。

3. 声明式调用 (Declarative Invocation)

一旦生成，这些 Invocable Actions 就可以像 Salesforce 提供的任何标准操作（如“创建记录”、“更新记录”）一样，在声明式工具中被发现和使用。最常见的应用场景是 Flow Builder。在 Flow 中，你可以直接拖拽一个“操作(Action)”元素，在类别中找到你注册的 External Service，然后选择相应的操作。Flow Builder 会自动展示出该操作需要的所有输入参数，以及调用成功后会返回的输出数据结构，你只需通过简单的点击和拖拽，就能将 Flow 中的变量映射到这些输入和输出上。

通过这种方式，External Services 巧妙地将复杂的 API 调用过程——构建 HTTP 请求、处理认证、序列化/反序列化 JSON 数据、处理响应——封装成了一个个简单的、对管理员友好的 Flow 元素。

---

示例代码

External Services 的核心“代码”是其所依赖的 OpenAPI 规范。以下是一个来自 Salesforce 官方文档的简化版银行服务 API 的 OpenAPI 2.0 规范示例。这份规范定义了查询银行账户信息的操作。

我们将通过这份 JSON 规范来理解 External Services 是如何工作的。当你将这份规范注册到 Salesforce 时，它会生成一个名为 `accountInfo` 的可调用操作。

{
  "swagger": "2.0",
  "info": {
    "title": "Bank Service API",
    "description": "API for retrieving bank account information.",
    "version": "1.0.0"
  },
  "host": "my-bank-service.herokuapp.com",
  "schemes": [
    "https"
  ],
  "paths": {
    "/accounts/{accountId}": {
      "get": {
        "summary": "Get Account Information",
        "description": "Retrieves details for a specific bank account.",
        "operationId": "accountInfo",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "accountId",
            "in": "path",
            "description": "The ID of the bank account to retrieve.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with account details.",
            "schema": {
              "$ref": "#/definitions/Account"
            }
          },
          "404": {
            "description": "Account not found."
          }
        }
      }
    }
  },
  "definitions": {
    "Account": {
      "type": "object",
      "properties": {
        "accountId": {
          "type": "string"
        },
        "accountName": {
          "type": "string"
        },
        "balance": {
          "type": "number"
        },
        "accountType": {
          "type": "string"
        }
      }
    }
  }
}

注释说明：

• "swagger": "2.0": 指明这是 OpenAPI 2.0 版本的规范。
• "host": 定义了 API 的基础 URL。在实际使用中，我们会用 Named Credential 来覆盖它。
• "paths": 这是核心部分，定义了所有的 API 端点。
• "/accounts/{accountId}": 定义了一个路径，其中 {accountId} 是一个路径参数，代表动态的账户 ID。
• "get": 定义了该路径支持的 HTTP GET 方法。
• "operationId": "accountInfo": 这是非常重要的一个字段。Salesforce 会用它来作为生成的可调用操作的名称。
• "parameters": 定义了此操作需要的所有输入参数。在这里，我们定义了一个名为 accountId 的路径参数 ("in": "path")，它是必需的 ("required": true")。在 Flow 中，这将成为一个名为 `accountId` 的输入字段。
• "responses": 定义了可能的响应。"200" 代表成功响应。
• "schema": { "$ref": "#/definitions/Account" }: 指明成功时返回的数据结构。它引用了 `definitions` 中定义的 `Account` 对象。
• "definitions": { "Account": { ... } }: 定义了可复用的数据模型。这里的 `Account` 对象包含了 `accountId`, `accountName`, `balance` 等字段。在 Flow 中，这将成为一个包含这些属性的输出变量，你可以通过 `Flow_Action_Output.accountName` 这样的方式来访问返回的数据。

---

注意事项

虽然 External Services 非常强大，但在实际项目咨询和落地时，我们必须充分考虑其限制和周边配置，以确保方案的健壮性和可维护性。

1. 权限与认证 (Permissions & Authentication)

必须使用 Named Credentials (命名凭证)！这是最佳实践，也是安全要求。Named Credential 将端点 URL 和认证信息（如用户名密码、OAuth 2.0、API Key 等）与 External Service 的定义本身分离开来。这样做的好处是：

• 安全性：敏感的凭证信息被安全地存储在 Salesforce 中，而不是硬编码在 API 规范里。
• 可维护性：当 API 的端点 URL 或密码在不同环境（如从 Sandbox 到 Production）发生变化时，你只需要更新 Named Credential，而无需重新注册或修改 External Service 和相关的 Flow。
• 简便性：Salesforce 会自动处理认证握手过程，你无需在 Flow 中手动构建认证头 (Authorization Header)。

此外，还需要为将要运行 Flow 的用户分配对该 External Service 的访问权限，这可以通过 Profile 或 Permission Set 来完成。

2. API 限制 (API Limits)

每一次通过 Flow 调用 External Service 操作，都会消耗 Salesforce 的 API Callout 限制。你需要牢记：

• 事务限制：每个 Salesforce 事务中最多只能执行 100 次 callout。如果你的 Flow 在一个循环中调用外部服务，需要非常小心，确保不会轻易超过这个限制。
- 超时限制：同步 callout 的超时时间最长为 120 秒。如果外部 API 响应缓慢，可能会导致 Flow 失败。
• 规范文件大小限制：OpenAPI 2.0 规范的大小不能超过 100,000 个字符，OpenAPI 3.0 则更大，但同样存在限制。过于复杂的 API 可能需要拆分成多个较小的服务进行注册。

3. 错误处理 (Error Handling)

永远不要假设外部 API 会永远正常工作。作为顾问，我总是强调要为失败设计。在 Flow Builder 中，每一个“操作”元素都有一个“Fault Path” (故障连接器)。你必须配置这个路径！

当 API 调用失败时（例如，返回 4xx 或 5xx 状态码，或发生网络超时），Flow 会沿着 Fault Path 执行。你可以在这个路径中实现补偿逻辑，例如：

• 向管理员发送一封包含错误详情的邮件通知。
• 在屏幕上向用户显示一个友好的错误提示信息。
• 将错误日志记录到一个自定义的“集成日志”对象中，方便后续排查。
• 更新相关记录的状态为“集成失败”。

4. 数据格式和复杂性

External Services 对于标准的数据结构支持得很好，但对于一些复杂的情况，可能会遇到挑战。例如，它不支持 multipart/form-data 类型的请求，这意味着你不能用它来上传文件。对于深度嵌套的 JSON 结构，虽然可以处理，但在 Flow 中访问这些嵌套层级的数据会变得比较繁琐。对于这种情况，可能需要考虑使用 Apex 定义的数据类型来简化处理。

---

总结与最佳实践

External Services 是 Salesforce 工具箱中一件强大的“瑞士军刀”，它为实现快速、低成本的声明式集成打开了大门，让 Salesforce 管理员和顾问能够解决以往必须依赖开发人员才能完成的业务需求。

作为一名咨询顾问，我为客户规划集成方案时，会遵循以下最佳实践：

1. 规范先行：在开始任何工作之前，务必从 API 提供方获取一份完整、有效且符合 OpenAPI 标准的规范文件。这是项目成功的基石。
2. 认证安全：始终坚持使用 Named Credentials 来管理所有端点和认证信息。这是安全和部署的最佳实践，没有例外。
3. 构建弹性的 Flow：为每一个外部服务调用都设计好 Fault Path。你的集成方案的健壮性取决于你对失败情况的处理能力。
4. 了解边界：清楚地认识到 External Services 的局限性。对于需要复杂数据转换、大批量数据同步、或长事务处理的场景，传统的 ETL 工具或定制的 Apex 解决方案可能仍然是更合适的选择。
5. 充分测试：在 Sandbox 环境中，针对不同的业务场景和异常情况进行详尽的测试，包括成功的调用、可预见的业务错误（如“账户不存在”）以及网络或服务器故障。
6. 文档化：清晰地记录每个 External Service 的用途、它所连接的 Named Credential、以及使用它的 Flow 列表，这将为未来的维护工作节省大量时间。

通过遵循这些原则，你可以充满信心地利用 External Services 为你的客户或企业构建出高效、可靠且易于维护的集成解决方案，真正释放 Salesforce 平台的全部潜力。