精通 Salesforce External Services：实现声明式 API 集成

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作就是将 Salesforce 与外部世界连接起来，打破数据孤岛，构建无缝的业务流程。在过去，这通常意味着编写大量的 Apex 代码。每当需要调用一个外部 REST API 时，我们都需要编写 Apex Callout 逻辑、处理 HTTP 请求和响应、解析 JSON，并编写相应的测试类。这个过程不仅耗时，而且对团队的技能要求较高，使得非开发人员（如 Salesforce 管理员）很难参与到集成工作中。

然而，随着 Salesforce 平台的发展，我们迎来了 External Services（外部服务）这一强大的声明式工具。External Services 彻底改变了我们进行 API 集成的方式。它允许我们通过提供一个 API 规范（通常是 OpenAPI 格式），自动在 Salesforce 中生成可供调用的操作（Invocable Actions）。这些操作可以像任何标准 Flow 元素一样，在 Flow Builder、Einstein Bots 或其他自动化工具中通过拖拽的方式使用，无需编写一行 Apex 代码。

这种“低代码”的集成方法带来了巨大的价值，其应用场景非常广泛：

1. 数据增强与验证

当创建新的潜在客户（Lead）或客户（Account）时，可以调用外部数据服务（如企查查、Clearbit）的 API，自动补充公司的行业、规模、地址等信息，确保数据的完整性和准确性。

2. 实时业务流程

在销售流程中，当一个机会（Opportunity）达到特定阶段时，可以自动调用外部的信用评级服务 API，获取客户的信用评分，并根据评分结果自动更新机会状态或通知相关人员。

3. 跨系统操作

当一个高优先级的个案（Case）被创建时，可以通过 Flow 触发一个 External Service 操作，自动在外部项目管理工具（如 JIRA）中创建一个工单，或在团队协作工具（如 Slack、Microsoft Teams）的指定频道中发送一条通知。

4. 物流与订单跟踪

对于电商或制造业，当订单发货后，可以调用快递公司的物流跟踪 API，将最新的物流状态实时同步回 Salesforce 的订单对象上，让客服人员和客户都能随时查看。

对于我们集成工程师而言，External Services 不仅是提高开发效率的利器，更是赋能业务团队、实现敏捷交付的关键。它让我们能将精力更多地投入到复杂的集成架构和逻辑设计上，而将标准的 API 调用工作交给平台去完成。

---

原理说明

要深入理解 External Services，我们需要了解其背后的核心工作流和关键组件。其原理可以概括为：“规范驱动，自动生成，安全调用”。

1. API 规范 (API Specification)

External Services 的起点是一个描述外部 API 结构的机器可读文件。Salesforce 支持行业标准的 OpenAPI 规范，具体版本为 OpenAPI 2.0 (JSON 格式) 和 OpenAPI 3.0 (JSON 或 YAML 格式)。这个规范文件就像一份 API 的“说明书”，它详细定义了以下内容：

• 服务器信息：API 的基础 URL。
• 路径 (Paths)：可用的 API 端点，例如 /users/{userId}。
• 操作 (Operations)：每个路径支持的 HTTP 方法，如 GET, POST, PUT, DELETE。
• 参数 (Parameters)：每个操作需要的输入，包括路径参数、查询参数、请求头和请求体。
• 响应 (Responses)：每个操作可能返回的 HTTP 状态码及其对应的响应体结构。
• 数据模型 (Schemas)：请求体和响应体中使用的 JSON 对象结构。

Salesforce 会解析这个文件，理解 API 的每一个细节，并将其转换为平台原生的元数据。

2. 命名凭证 (Named Credential)

在集成中，安全永远是第一位的。我们绝不能将 API 密钥、用户名、密码等敏感信息硬编码在代码或配置中。Named Credential（命名凭证）是 Salesforce 解决这个问题的标准方案。

它将认证信息（Authentication）和端点 URL（Endpoint URL）封装在一个可管理的组件中。当我们注册 External Service 时，我们不直接提供 API 的完整 URL，而是将其与一个 Named Credential 关联。这样做的好处是：

• 认证解耦：Salesforce 负责处理认证协议，无论是基本的用户名密码、API Key，还是复杂的 OAuth 2.0 流程。我们只需要在 Named Credential 中进行一次性配置。
• 安全性：凭证信息被安全地存储在 Salesforce 平台，并且可以通过简档（Profile）和权限集（Permission Set）进行访问控制，避免了敏感信息泄露的风险。
• 环境管理：在从沙箱（Sandbox）部署到生产（Production）环境时，我们只需要修改目标环境中 Named Credential 的配置（例如，将 URL 从测试环境指向生产环境），而无需修改任何 Flow 或代码。

3. 自动生成可调用操作 (Invocable Action Generation)

当我们将 OpenAPI 规范和 Named Credential 提供给 Salesforce 后，平台会在后台执行以下操作：

1. 解析规范：读取 OpenAPI 文件的所有路径、操作和数据模型。
2. 创建元数据：为每个 API 操作（例如，`POST /accounts`）生成一个对应的可调用操作 (Invocable Action)。
3. 转换数据类型：将规范中定义的 JSON 数据类型（如 string, number, boolean, object）映射到 Flow 和 Apex 支持的数据类型。例如，一个复杂的 JSON 对象会变成一个 Apex 定义的变量类型，在 Flow 中可以方便地进行数据读写。

最终的结果是，在 Flow Builder 的“操作”元素中，你会看到一个以你的 External Service 命名的新分类，里面包含了所有可以使用的 API 操作，就像使用标准的“发送邮件”或“创建记录”操作一样简单。

---

示例代码

虽然 External Services 的主要优势在于声明式工具，但它生成的服务和操作同样可以在 Apex 中以编程方式调用。这为我们集成工程师提供了极大的灵活性，当业务逻辑过于复杂，无法用 Flow 实现时，我们依然可以利用 External Services 的便利性，而无需手动编写复杂的 HTTP Callout。

以下示例代码来自 Salesforce 官方文档，演示了如何在 Apex 中调用一个已经注册的、名为 `BankService` 的 External Service，该服务有一个名为 `accountInfo` 的操作。

// 假设我们已经通过 OpenAPI 规范注册了一个名为 'BankService' 的外部服务
// 该服务有一个名为 'accountInfo' 的操作，需要一个 'accountId' 字符串作为输入
// 并返回一个包含账户信息的复杂对象

// 1. 准备调用所需的参数。输入参数必须是一个 Map<String, Object> 类型
Map<String, Object> serviceInputs = new Map<String, Object>();
serviceInputs.put('accountId', 'a001xxxxxxxxx'); // 'accountId' 是 OpenAPI 规范中定义的操作参数名

// 2. 准备一个 Map 用于存放可能出现的额外 HTTP 头信息（可选）
Map<String, String> serviceHeaders = new Map<String, String>();
serviceHeaders.put('x-custom-header', 'MyHeaderValue');

// 3. 使用 ExternalService.invoke 方法发起同步调用
// 语法: invoke(namespace, serviceName, serviceAction, inputs, headers)
// - namespace: 如果服务在受管包中，则为包的命名空间；否则为 null
// - serviceName: 注册的外部服务的名称
// - serviceAction: 要调用的操作的名称
// - inputs: 包含输入参数的 Map
// - headers: 包含额外请求头的 Map (可选)
try {
    ExternalService.InvocationResult result = ExternalService.invoke(
        null,           // 没有命名空间
        'BankService',
        'accountInfo',
        serviceInputs,
        serviceHeaders
    );

    // 4. 检查调用是否成功
    if (result.isSuccess()) {
        // 5. 获取 HTTP 状态码和响应体
        Integer responseCode = result.getResponseCode();
        String responseBody = result.getResponse();
        System.debug('HTTP Status Code: ' + responseCode);
        System.debug('Response Body: ' + responseBody);

        // 6. 将响应解析为 Map<String, Object> 以便访问具体数据
        // Salesforce 自动将 JSON 响应反序列化为 Apex 对象
        Map<String, Object> responseMap = result.getResponseMap();
        
        // 假设响应体是 { "account": { "name": "John Doe", "balance": 1000.0 } }
        if (responseMap.containsKey('account')) {
            Map<String, Object> accountDetails = (Map<String, Object>) responseMap.get('account');
            String accountName = (String) accountDetails.get('name');
            Decimal accountBalance = (Decimal) accountDetails.get('balance');
            System.debug('Account Name: ' + accountName);
            System.debug('Account Balance: ' + accountBalance);
        }

    } else {
        // 7. 如果调用失败，处理错误
        System.debug('Error calling service. Status code: ' + result.getResponseCode());
        System.debug('Error message: ' + result.getErrorMessage());
    }

} catch (Exception e) {
    // 8. 捕获可能发生的其他异常，例如服务不可用或配置错误
    System.debug('An unexpected error occurred: ' + e.getMessage());
}

这个例子清晰地展示了，即使在 Apex 中，External Services 也极大地简化了 API 调用。我们不再需要关心 `HttpRequest`, `HttpResponse`, `JSON.serialize`, `JSON.deserialize` 等底层细节，只需关注业务逻辑本身。

---

注意事项

作为一名严谨的集成工程师，在使用 External Services 时，我们必须清楚其限制和需要注意的关键点，以确保构建的解决方案是稳定、安全和可扩展的。

1. 权限与安全 (Permissions and Security)

• 创建权限：要注册、编辑或删除 External Services，用户需要“Customize Application”权限。
• 运行权限：运行调用 External Services 的 Flow 或其他自动化工具的用户，需要相应的运行权限。此外，必须确保该用户可以通过简档或权限集访问关联的 Named Credential。
• 数据安全：始终使用 Named Credential 来管理认证信息。避免在 API 规范中硬编码任何敏感信息。

2. API 限制 (API Limits)

External Services 的调用同样受 Salesforce 平台的调控器和限制 (Governor Limits) 约束：

• Callout 限制：每次 Apex 事务中同步 Callout 的总数有限制（通常是 100 个）。每次通过 Flow 调用一个 External Service 操作，都会消耗一个 Callout。
• 超时限制 (Timeout)：对外部服务的调用有超时限制，最长为 120 秒。如果外部 API 响应缓慢，可能会导致调用失败。
• Payload 大小限制：请求和响应的 Payload 大小存在限制。对于同步操作，通常限制在 3MB 左右。对于需要处理大数据量的场景，这可能是一个瓶颈。
• OpenAPI 规范限制：规范文件本身的大小不能超过 100KB。同时，并非所有的 OpenAPI 结构都被支持，例如，`oneOf`, `anyOf`, `allOf` 等复杂的组合模式以及递归模式可能无法正确解析。

3. 错误处理 (Error Handling)

健壮的集成方案必须有完善的错误处理机制。

• 在 Flow 中：务必为调用 External Service 的“操作”元素添加故障路径 (Fault Path)。当 API 调用失败（例如，返回 4xx 或 5xx 状态码，或发生网络超时）时，流程会进入故障路径，你可以在其中执行记录错误日志、发送通知邮件、回滚操作等逻辑。
• 在 Apex 中：如示例代码所示，总是使用 `try-catch` 块来包裹 `ExternalService.invoke` 调用，并检查 `result.isSuccess()` 的返回值，以优雅地处理成功和失败两种情况。

---

总结与最佳实践

External Services 是 Salesforce 平台集成工具箱中一颗璀璨的明珠。它成功地将复杂的 API 调用过程抽象化、声明化，极大地降低了集成的门槛，提高了交付速度。对于我们集成工程师来说，它让我们能够更高效地响应业务需求，并构建出更易于维护的解决方案。

为了最大化 External Services 的价值，我建议遵循以下最佳实践：

1. 规范先行 (Specification First)：在注册服务之前，务必确保你的 OpenAPI 规范是完整、有效且符合 Salesforce 支持的标准的。使用 Swagger Editor 或类似工具进行验证和调试，可以事半功倍。
2. 设计可重用的服务 (Design for Reusability)：将外部 API 按照业务领域（如“订单服务”、“用户服务”）进行划分和注册。一个设计良好的 External Service 应该包含一组相关的、可被多个不同业务流程重用的操作。
3. 优先选择声明式工具 (Declarative First)：尽可能在 Flow Builder 中使用 External Services。只有当业务逻辑的复杂度超出 Flow 的能力范围时，才考虑在 Apex 中进行调用。这符合 Salesforce “Clicks, not Code” 的核心理念。
4. 强化安全基石 (Solidify Security Foundations)：始终、无一例外地使用 Named Credential。根据最小权限原则，精确控制哪些用户和简档可以访问这些凭证和执行外部调用。
5. 监控与日志 (Monitoring and Logging)：建立一套机制来监控外部服务的调用情况。在 Flow 的故障路径或 Apex 的 catch 块中，创建自定义的日志对象来记录失败的调用、请求参数和错误信息，这将为问题排查提供宝贵的数据。

总而言之，熟练掌握 External Services，并将其与 Named Credential、Flow 和 Apex 相结合，是每一位 Salesforce 集成工程师的必备技能。它不仅是一种技术，更是一种能让我们更快、更好地连接企业内外的强大思维方式。