Salesforce External Services：咨询顾问视角下的声明式 API 集成指南

背景与应用场景

作为一名 Salesforce 咨询顾问，我经常遇到的一个核心业务挑战是如何将 Salesforce 与企业生态系统中的其他外部系统无缝连接。在过去，这通常意味着需要投入大量的开发资源来编写、测试和维护复杂的 Apex Callouts。这不仅延长了项目周期，增加了成本，也使得非开发人员（如 Salesforce 管理员）在面对集成需求时束手无策。然而，随着 Salesforce 平台的发展，我们迎来了一个颠覆性的工具：External Services（外部服务）。

External Services 是 Salesforce 平台提供的一项强大的声明式（Declarative）功能，它允许我们通过点击而非代码的方式，将外部的 REST API 集成到 Salesforce 中。其核心思想是通过解析一个标准的 API 规范文件（如 OpenAPI），自动生成可以在 Flow（流）、Einstein Bots 或 Omni-Studio 中直接调用的“可调用操作” (Invocable Actions)。

对于咨询顾问而言，这意味着我们能够为客户提供更敏捷、更经济、更易于维护的集成解决方案。我们可以赋能客户的 Salesforce 管理员，让他们亲自构建和维护一些中低复杂度的集成，从而将宝贵的开发资源集中在更复杂的业务逻辑上。

典型的应用场景包括：

• 数据增强：当销售人员创建一个新的“潜在客户” (Lead) 时，自动调用外部数据服务（如企业征信、地址校验）来补充和验证信息，提高数据质量。
• 实时查询：在“个案” (Case) 页面上，客服人员可以点击一个按钮，通过 Screen Flow 实时查询外部物流系统的包裹状态，并立即告知客户。
• 跨系统操作：当一个“业务机会” (Opportunity) 的阶段更新为“已成交”时，自动触发一个 Flow，调用外部财务系统的 API 来创建一个新的发票或合同记录。
• 简化用户体验：将多个外部系统的功能整合到一个统一的 Salesforce Screen Flow 界面中，用户无需离开 Salesforce 即可完成一系列跨系统操作，例如在一个流程中完成信用额度申请、审批和激活。

---

原理说明

External Services 的工作原理可以概括为一个“注册-生成-调用”的过程，其背后依赖于两个 Salesforce 核心组件：OpenAPI 规范和 Named Credentials（命名凭据）。

1. 定义与注册 (Define & Register)

首先，你需要获取外部服务的 API 规范。External Services 支持业界标准的 OpenAPI 规范，具体版本为 OpenAPI 2.0 (Swagger) 和 OpenAPI 3.0，格式可以是 JSON 或 YAML。这份规范文件就像一份“API 说明书”，它用标准化的方式详细描述了 API 的所有细节，包括：

• 可用的端点 (Endpoints) 路径（例如 /users/{userId}）。
• 支持的 HTTP 方法（例如 GET, POST, PUT, DELETE）。
• 请求所需的参数（路径参数、查询参数、请求体等）及其数据类型。
• 响应的结构和数据类型。

你可以在 Salesforce 的“设置”菜单中找到“外部服务”，然后通过上传这个规范文件或提供一个 URL 来注册一个新的外部服务。Salesforce 会在后台解析这份“说明书”。

2. 认证管理 (Authentication Management)

在调用外部 API 时，身份验证是必不可少的一环。直接在代码或配置中硬编码密码或密钥是极其危险且不专业的做法。Salesforce 为此提供了最佳实践：Named Credentials（命名凭据）。

Named Credential 将 API 的端点 URL 和认证信息（如用户名密码、API Key、OAuth 2.0 令牌等）打包在一起进行管理。当你在注册 External Service 时，可以将其关联到一个预先配置好的 Named Credential。这样做的好处是：

• 安全性：认证信息被 Salesforce 安全地存储和管理，避免了敏感信息的泄露。
• 可维护性：当外部系统的密码或密钥变更时，你只需要更新 Named Credential 即可，所有引用它的 External Service 和 Flow 都无需修改。
• 便捷性：Salesforce 会自动处理认证流程，例如 OAuth 2.0 的令牌刷新，你无需在 Flow 中手动处理这些复杂逻辑。

3. 生成与调用 (Generate & Invoke)

一旦注册完成，Salesforce 就会根据 OpenAPI 规范为其中的每一个操作（Operation）自动生成一个对应的“可调用操作” (Invocable Action)。例如，规范中一个用于创建用户的 POST /users 操作，可能会在 Flow Builder 中生成一个名为“Create User (myExternalService)” 的操作元素。

这个生成的操作会自动包含规范中定义的输入参数和输出参数。你可以在 Flow 中像使用任何其他标准元素一样，将它拖放到画布上，通过变量传递输入值，并处理它的输出结果。整个过程无需编写一行 Apex 代码，实现了真正的声明式集成。

---

示例代码

External Services 本身是无代码的，但它的基础是 OpenAPI 规范。理解规范的结构至关重要。以下是一个来自 Salesforce 官方文档的简化版银行服务 OpenAPI 2.0 规范示例，用于演示如何定义创建和查询账户的操作。

这份 JSON 文件描述了一个简单的银行 API，它有两个主要操作：一个是使用 POST 方法在 /accounts 路径下创建新账户；另一个是使用 GET 方法在 /accounts/{accountName} 路径下根据账户名查询账户详情。

{
  "swagger": "2.0",
  "info": {
    "title": "Bank Service",
    "description": "API for a simple bank service.",
    "version": "1.0.0"
  },
  "host": "my-bank-service.herokuapp.com",
  "schemes": [
    "https"
  ],
  "paths": {
    "/accounts": {
      "post": {
        "summary": "Create Account",
        "description": "Creates a new bank account.",
        "parameters": [
          {
            "name": "account",
            "in": "body",
            "description": "The account to create.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully created account.",
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        }
      }
    },
    "/accounts/{accountName}": {
      "get": {
        "summary": "Get Account",
        "description": "Retrieves account details by name.",
        "parameters": [
          {
            "name": "accountName",
            "in": "path",
            "description": "The name of the account to retrieve.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation.",
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Account": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "balance": {
          "type": "number"
        },
        "id": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "balance"
      ]
    }
  }
}

规范解析：

• swagger: "2.0": 声明了这是一个 OpenAPI 2.0 规范。
• info: 提供了关于 API 的元数据，如标题和描述。
• host: 定义了 API 的主机名。这个值通常会被关联的 Named Credential 中的 URL 覆盖。
• paths: 这是规范的核心，定义了所有可用的 API 端点。
• /accounts -> post: 这个部分定义了一个创建账户的操作。当 Salesforce 解析它时，会生成一个名为 "Create Account" 的可调用操作。它需要一个名为 account 的请求体（body）作为输入，其结构由 #/definitions/Account 定义。成功后，它会返回一个同样结构的账户对象。
• /accounts/{accountName} -> get: 这个部分定义了一个查询账户的操作。它会生成一个名为 "Get Account" 的可调用操作。它需要一个名为 accountName 的路径参数（path parameter）作为输入。
• definitions: 这里定义了可重用的数据模型。Account 模型定义了一个包含 name, balance, 和 id 字段的对象。在 Flow 中，这会被转换为一个 Apex-defined 变量类型，方便你访问其属性。

---

注意事项

作为咨询顾问，在向客户推荐和实施 External Services 方案时，必须清晰地沟通其能力边界和潜在风险。以下是一些关键的注意事项：

1. 权限与安全

• 设置权限: 创建和管理 External Services 需要用户拥有“自定义应用程序” (Customize Application) 权限。
• 运行权限: 运行包含外部服务调用的 Flow 的用户，需要有权限访问该 Flow 以及所使用的 Named Credential。你需要合理配置 Named Credential 的权限，以控制哪些用户或简档可以代表 Salesforce 调用外部系统。

2. API 限制与 Governor Limits

• 调用限制: Flow 中的每一个外部服务操作都计为一个 Callout。你必须遵守 Salesforce 的事务性 Governor Limits，例如每个事务最多 100 个 Callout。在设计循环调用 API 的 Flow 时要格外小心，避免超出限制。
• 规范文件限制: Salesforce 对 OpenAPI 规范文件本身也有一些限制，例如最大文件大小（目前为 100KB），以及规范中定义的操作和对象的最大数量。过于复杂的 API 可能需要拆分成多个较小的外部服务进行注册。
• 不支持的 OpenAPI 特性: Salesforce 的解析器并不支持 OpenAPI 规范的全部特性。例如，它对某些复合模式（如 oneOf, anyOf, allOf）和递归模式的支持有限。在开始实施前，务必用你的规范文件进行测试，确认所有需要的操作和数据类型都能被正确解析。

3. 错误处理

这是任何集成项目中最重要的部分。外部 API 可能会因为网络问题、认证失败、服务器错误或无效输入而失败。在 Flow Builder 中，你必须为每一个外部服务操作元素连接一条“故障路径” (Fault Path)。

在故障路径中，你可以设计补偿逻辑，例如：

• 向用户显示一条友好的错误提示。
• 创建一个日志记录来捕获错误详情（$Flow.FaultMessage）。
• 向系统管理员发送一封邮件或 Chatter 通知。
• 尝试回滚之前的操作或将记录状态设置为“错误”。

4. 事务控制

一个常见的误区是关于事务边界。在一个 Flow 事务中，如果你先执行了数据库操作（如创建记录），然后再进行 Callout，那么这个数据库操作会被立即提交。如果随后的 Callout 失败，之前已提交的数据库操作不会自动回滚。这是一个关键的设计考量点。最佳实践通常是先执行所有 Callout，获取所需数据，然后再在事务的末尾统一执行所有的数据库写入操作。

---

总结与最佳实践

External Services 是 Salesforce 集成工具箱中一件极其强大的工具，它极大地降低了 API 集成的门槛，使得快速响应业务需求成为可能。它完美契合了“低代码”开发的理念，让集成工作从数周的编码缩短到数小时的配置。

作为咨询顾问，为客户提供成功的集成方案，我建议遵循以下最佳实践：

1. 优先选择声明式工具：在面对集成需求时，首先评估 External Services 是否适用。对于标准的、基于 REST/JSON 的请求-响应式集成，它应该是首选方案。
2. 验证你的 API 规范：在上传到 Salesforce 之前，使用在线的 OpenAPI 验证工具检查规范的语法和结构是否正确，这可以避免很多不必要的麻烦。
3. 始终使用 Named Credentials：这是处理认证的唯一正确方式。它安全、可扩展且易于管理，尤其是在需要在不同环境（Sandbox, Production）之间迁移时。
4. 设计可复用的 Flow：将调用外部服务的逻辑封装在可被其他 Flow 调用的子流 (Subflow) 中。这提高了模块化和可重用性。
5. 构建弹性的错误处理机制：永远不要假设外部服务是 100% 可靠的。为每一个 Callout 设计周全的故障路径，是衡量一个集成方案是否成熟的关键标志。
6. 了解并尊重限制：在方案设计阶段就要充分考虑 Salesforce 的 Governor Limits 和 External Services 自身的功能限制，为复杂或大容量的集成场景选择更合适的工具（如 MuleSoft 或自定义 Apex）。

通过遵循这些原则，我们可以利用 External Services 为客户构建出既强大又灵活、既快速又稳健的集成解决方案，真正实现 Salesforce 作为企业应用中心的价值。