Salesforce 外部服务：深入解析声明式 API 集成

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作就是将 Salesforce 与外部系统连接起来，实现数据的无缝流转和业务流程的自动化。在过去，实现这一目标的主要方式是编写 Apex Callouts。这意味着我们需要编写 Apex 代码来构建 HTTP 请求、处理认证、解析 JSON/XML 响应，并编写大量的单元测试来保证代码覆盖率。这个过程不仅耗时，而且对开发人员的技能要求较高，同时也增加了项目的维护成本。

然而，随着 Salesforce 平台的不断演进，我们迎来了更加高效和敏捷的集成工具。其中，External Services (外部服务) 就是一个革命性的功能，它彻底改变了我们进行出站 REST API 集成的方式。External Services 允许我们通过一种声明式、“点击式”的方法，将外部的 RESTful API 集成到 Salesforce 中，而无需编写一行 Apex 代码。

这项技术的核心是 OpenAPI Specification (开放应用程序接口规范)，它是一种用于描述 REST API 的行业标准。通过提供一个 OpenAPI 规范文件，Salesforce 能够自动理解外部 API 的结构，并将其中的操作（Operations）转换为可以在 Flow Builder (流程构建器)、Einstein Bots 或 OmniStudio 中直接调用的“可调用操作” (Invocable Actions)。

常见的应用场景包括：

• 实时数据查询：从外部物流系统（如顺丰、FedEx）查询订单的实时物流状态，并将其展示在 Salesforce 的“订单”或“个案”页面上。
• 数据验证与丰富：在创建新客户（Account）或联系人（Contact）时，调用外部服务（如企查查、天眼查）验证企业信息的准确性，或调用地址验证服务来规范化地址格式。
• 外部系统操作：当 Salesforce 中的一个机会（Opportunity）状态变为“已结束并赢得”时，自动触发一个 Flow，通过 External Service 调用外部 ERP 系统（如 SAP、Oracle）的 API 来创建销售订单。
• 金融服务集成：在处理贷款申请时，从征信机构的 API 获取申请人的信用评分，并根据评分结果自动更新申请状态。

对于集成工程师来说，External Services 意味着我们可以将更多精力聚焦在业务流程的设计和优化上，而不是陷入繁琐的底层代码实现中。它极大地降低了集成的技术门槛，让 Salesforce 管理员也能参与到简单的集成任务中，从而提高了整个团队的交付效率。

---

原理说明

要理解 External Services 的工作原理，我们必须首先了解其基石——OpenAPI Specification。OpenAPI 规范（以前称为 Swagger 规范）是一个与语言无关的接口描述文件，用于描述 RESTful API。它以 JSON 或 YAML 格式定义了 API 的所有细节，包括：

• 端点 (Endpoints)：可用的 URL 路径，如 /users/{userId}。
• 操作 (Operations)：每个端点支持的 HTTP 方法，如 GET, POST, PUT, DELETE。
• 参数 (Parameters)：每个操作所需的输入参数，包括其名称、位置（路径、查询、请求头、请求体）、数据类型等。
• 响应 (Responses)：每个操作可能返回的 HTTP 状态码及其对应的响应体结构。
• 数据模型 (Schemas/Definitions)：API 中使用的复杂数据对象的结构定义。

External Services 的工作流程非常直观：

1. 注册服务：您首先需要获取目标外部服务的 OpenAPI 规范文件。然后，在 Salesforce 的“设置”菜单中，导航到“外部服务”，并创建一个新的外部服务。在此过程中，您需要选择规范类型（如 OpenAPI 2.0 或 3.0）并上传或粘贴规范内容。
2. 规范解析与操作生成：Salesforce 会解析您提供的 OpenAPI 规范。对于规范中定义的每一个操作（例如，一个 `POST /accounts` 操作），Salesforce 都会在后台自动生成一个对应的“可调用操作”。这个操作封装了所有底层的技术细节，如构建 HTTP 请求、序列化请求体、反序列化响应等。
3. 认证配置：为了安全地调用外部 API，您必须配置认证信息。最佳实践是使用 Named Credentials (命名凭证)。您可以在 Named Credential 中定义 API 的端点 URL 和认证细节（如用户名密码、OAuth 2.0、API 密钥等）。在注册外部服务时，您可以将其与一个 Named Credential 关联起来。这样做的好处是，您无需在 Flow 或代码中硬编码任何敏感信息，并且可以轻松地在不同环境（沙盒、生产）之间切换认证配置。
4. 在 Flow 中调用：一旦外部服务注册成功，其生成的所有可调用操作都会出现在 Flow Builder 的“操作”元素中。您可以像调用任何标准 Salesforce 操作一样，将它们拖拽到画布上，为其提供输入参数（通常来自屏幕输入或 Salesforce 记录），并处理其输出结果。

从集成工程师的角度来看，这个过程将复杂的 API 调用抽象成了一个简单的、可配置的 Flow 组件。我们不再关心 `HttpRequest` 或 `HttpResponse` 对象，而是专注于业务逻辑的流转：何时触发调用？输入数据从哪里来？调用成功或失败后应该执行什么后续步骤？

---

示例代码

这里的“代码”并非 Apex，而是 External Services 的“原料”——OpenAPI 2.0 规范。以下示例来自 Salesforce 官方文档，描述了一个简单的银行服务 API，它允许我们查询账户信息和添加新账户。

{
  "swagger": "2.0",
  "info": {
    "title": "Bank Service",
    "description": "API for a bank service",
    "version": "1.0"
  },
  "host": "my-bank-service.com",
  "schemes": [
    "https"
  ],
  "basePath": "/accounts",
  "paths": {
    "/": {
      "post": {
        "summary": "Add a new account",
        "description": "Creates a new bank account.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A new account was created."
          }
        }
      }
    },
    "/{accountId}": {
      "get": {
        "summary": "Get account information",
        "description": "Returns account information for a given account ID.",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Account": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "accountType": {
          "type": "string"
        }
      }
    }
  }
}

注释说明：

• "swagger": "2.0": 声明了此规范遵循 OpenAPI 2.0 标准。
• "host" 和 "basePath": 定义了 API 的基础 URL。实际的请求地址会是 https://my-bank-service.com/accounts。在 Salesforce 中，这个地址通常会被 Named Credential 中的 URL 覆盖。
• "paths": 这是规范的核心，定义了所有可用的 API 端点。
  • "/" 和 "post": 定义了一个在 /accounts 路径上的 `POST` 请求，用于创建新账户。它的输入参数（parameters）来自请求体（"in": "body"），并且其结构由 #/definitions/Account 定义。
  • "/{accountId}" 和 "get": 定义了一个在 /accounts/{accountId} 路径上的 `GET` 请求。它需要一个名为 `accountId` 的路径参数（"in": "path"）。其成功的响应（"200"）会返回一个符合 #/definitions/Account 结构的对象。
• "definitions": 定义了可复用的数据模型。这里的 "Account" 模型描述了一个包含 name, id, 和 accountType 字段的对象。当 Salesforce 解析这个规范时，它会为这个模型创建一个对应的 Apex 定义的数据类型，以便在 Flow 中作为输入或输出变量使用。

当您将此规范注册到 Salesforce External Services 后，Salesforce 会自动生成两个可调用的操作，可能命名为 "addAccount" 和 "getAccountInformation"，您可以在 Flow 中直接使用它们。

---

注意事项

虽然 External Services 非常强大，但在实际使用中，我们必须考虑以下几点：

1. 权限和安全：
   • Named Credentials 是首选：始终使用 Named Credentials 来管理端点 URL 和认证。这不仅安全，而且便于管理。
   • 用户权限：创建和管理 External Services 需要“自定义应用程序”权限。运行调用这些服务的 Flow 的用户，则需要相应的 Flow 运行权限，并且可能需要访问 Named Credentials 的权限（通过权限集）。
2. API 限制：
   • Salesforce Governor Limits：通过 External Services 发起的调用同样受制于 Salesforce 的通用调出限制，例如每个事务的同步调出次数（最多100次）、总调出超时时间（最多120秒）等。
   • 规范限制：Salesforce 对 OpenAPI 规范本身也有一些限制，例如文件大小不能超过 100 KB，操作数量、对象属性数量等都有上限。过于复杂的规范可能无法被成功注册。
   • 不支持的特性：并非所有的 OpenAPI 特性都被完全支持。例如，对于一些复杂的继承和多态（如 `oneOf`, `anyOf`），或者某些特定的认证方案，支持可能有限。在使用前，务必查阅最新的 Salesforce 官方文档以确认支持范围。
3. 错误处理：
   • 使用 Fault 路径：在 Flow Builder 中，当您添加一个调用 External Service 的“操作”元素时，一定要为其连接一条“错误路径” (Fault Path)。当 API 调用失败时（例如，返回 4xx 或 5xx 错误码，或发生网络超时），流程会沿着这条路径执行。您可以在错误路径中添加记录日志、向用户显示错误消息或发送通知等补偿逻辑。
   • 解析错误响应：External Services 会将外部 API 的错误信息封装在 Flow 的 Fault 变量中，您可以访问这些信息来了解失败的具体原因。
4. 事务控制：
   • 在 Salesforce 的事务模型中，在一个事务内执行了 DML 操作（如创建、更新记录）之后，就不能再进行同步的 API 调出。如果您的 Flow 需要先更新 Salesforce 记录，然后再调用外部服务，您必须将调出操作放在一个独立的、异步的路径中（例如，使用“异步路径”或安排一个稍后运行的路径）。

---

总结与最佳实践

Salesforce External Services 是集成工具箱中一件极为重要的工具。它成功地将 REST API 集成从一个纯粹的开发任务，转变为一个可以通过声明式配置快速完成的集成任务，极大地提升了敏捷性和开发效率。

作为一名集成工程师，我的最佳实践建议是：

• 明确使用场景：当外部 API 提供了清晰的 OpenAPI 规范，且集成逻辑相对直接（即可以通过 Flow 的逻辑实现）时，External Services 是首选方案。它能让你快速交付价值。
- 优先于 Apex Callouts：对于新的出站 REST 集成需求，首先评估是否可以使用 External Services。只有在遇到以下情况时才考虑退回到传统的 Apex Callout： - 外部 API 没有提供 OpenAPI 规范，且手动创建规范的成本过高。 - 需要在调用前后执行非常复杂的、无法在 Flow 中实现的业务逻辑。 - 需要处理 External Services 不支持的认证机制或数据结构。 - 需要对 HTTP 请求头或请求过程进行精细的、程序化的控制。
• 与 API 提供方协作：在项目早期，就与外部 API 的提供方沟通，确保他们能提供符合 OpenAPI 2.0 或 3.0 标准的、结构良好的规范文件。一个高质量的规范是成功集成的一半。
• 设计可复用的 Flow：将调用外部服务的逻辑封装在可复用的子流程（Subflow）中。这样，不同的主流程可以根据需要调用这个子流程，从而提高了模块化程度和可维护性。
• 充分测试：虽然无需编写 Apex 测试类，但您必须在沙盒环境中对整个业务流程进行端到端的测试，包括成功路径和各种预期的错误场景。确保您的错误处理逻辑能够如期工作。

总而言之，External Services 不仅仅是一个功能，它代表了一种现代化的集成理念：通过标准化和声明式工具，将复杂的技术问题简单化，使我们能够更专注于实现真正的业务价值。掌握它，是每一位 Salesforce 专业人员，尤其是集成领域专家的必备技能。