精通 Salesforce Named Credentials：构建稳健且安全的 API 集成

九月 23, 2025

身份：Salesforce 集成工程师

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作核心就是将 Salesforce 平台与外部世界连接起来。无论是从第三方服务获取数据、将交易信息同步到 ERP 系统，还是调用自定义的微服务，API 集成都扮演着至关重要的角色。然而，一个成功的集成不仅仅是让数据流动起来，更关键的是如何以一种安全、可维护、可扩展的方式来实现它。

在早期，开发者们常常将认证信息（如 API 密钥、用户名、密码）和端点 URL (Endpoint URL) 硬编码在 Apex 代码中，或者存储在自定义设置 (Custom Settings) / 自定义元数据 (Custom Metadata) 中。这种方式存在诸多弊端：

安全风险：凭证以明文或易于解码的形式存储，一旦代码或元数据泄露，将导致严重的安全漏洞。
维护噩梦：当外部系统的端点 URL 或凭证变更时（例如从沙箱切换到生产环境，或定期轮换密码），我们需要修改代码或元数据并重新部署，费时费力且容易出错。
缺乏灵活性：难以针对不同用户使用不同的凭证进行认证。

为了解决这些痛点，Salesforce 推出了 Named Credentials (命名凭证)。它是一种将 API 端点 URL 和认证信息从代码中分离出来的配置化功能，从根本上改变了我们在 Salesforce 中进行外部调用的方式。通过 Named Credentials，我们可以将集成的安全性和可维护性提升到一个全新的水平。它适用于任何需要从 Salesforce 发起 HTTP 调用的场景，例如：

连接到 Google、Twitter 等公共 API。
与企业内部的 SAP 或 Oracle ERP 系统进行数据同步。
调用部署在 AWS 或 Heroku 上的自定义微服务。
集成第三方支付网关或物流查询服务。

原理说明

Named Credentials 的核心思想是“解耦”——将调用的“目标地址”和“身份凭证”与 Apex 代码分离开来，交由 Salesforce 平台进行统一、安全的管理。当你的 Apex 代码需要进行外部调用时，它不再直接引用一个具体的 URL，而是引用一个预先配置好的 Named Credential 的名称。

Salesforce 在接收到这个请求后，会根据 Named Credential 的配置，自动完成以下工作：

解析出真实的端点 URL。
根据指定的认证协议（如 OAuth 2.0, Basic Auth 等），获取并生成相应的认证头（例如 `Authorization` Header）。
将认证头附加到 HTTP 请求中，然后将请求发送到目标端点。

这个过程对开发者是透明的，我们只需关心业务逻辑，而无需处理复杂的认证流程和凭证管理。一个 Named Credential 主要由以下几个关键部分组成：

1. 基本信息

Label (标签) 和 Name (名称)：用于在 Salesforce 界面和代码中识别该 Named Credential。代码中引用的就是这个 `Name`。

URL：集成的基础端点 URL，例如 `https://api.example.com`。在代码中，我们只需要指定相对路径（如 `/v1/orders`），Salesforce 会自动将其与此基础 URL 拼接。

2. 认证 (Authentication)

这是 Named Credentials 的精髓所在。它支持多种认证协议：

Password Authentication：即基本认证 (Basic Authentication)，提供用户名和密码。Salesforce 会自动将其编码为 Base64 字符串并放入 `Authorization: Basic [encoded_string]` 头中。
OAuth 2.0：适用于需要 OAuth 2.0 流程的 API。它与 Salesforce 的 Auth. Provider (身份验证提供商) 紧密集成，可以自动处理 token 的获取、刷新和附加，极大地简化了 OAuth 调用的复杂性。
JWT (JSON Web Token)：支持使用 JWT 进行服务器到服务器的认证。
JWT Token Exchange：支持 JWT 令牌交换流程。
AWS Signature Version 4：专用于调用 Amazon Web Services (AWS) API，Salesforce 会自动处理复杂的签名生成过程。

3. 外部凭证 (External Credential) 与主体 (Principal)

近年来，Salesforce 对 Named Credentials 进行了现代化改造，引入了 External Credential (外部凭证) 和 Principal (主体) 的概念，使其变得更加模块化和灵活。

External Credential：它将认证协议和权限集分离开来，专门负责定义“如何”进行认证（例如，使用哪个 OAuth 流程，哪个客户端密钥）。
Principal：它将用户（或一组用户，通过权限集）与 External Credential 关联起来，定义了“谁”有权使用这个凭证。
Named Credential：现在主要负责定义“调用哪里”（即端点 URL）。

这种新的三层结构（Named Credential -> External Credential -> Principal）提供了更精细的访问控制和更高的重用性。例如，多个 Named Credentials 可以共享同一个 External Credential，如果认证方式变更，只需修改一处即可。

4. 特性开关

Generate Authorization Header (生成授权页眉)：默认勾选。Salesforce 会自动根据认证配置生成 `Authorization` 头。如果外部服务需要一个非标准的认证头，你可以取消勾选此项，并手动在 Apex 代码中构建它。
Allow Merge Fields in HTTP Header/Body (允许在 HTTP 头/正文中使用合并字段)：这是一个非常强大的功能，允许你在请求头和请求体中动态插入 Salesforce 字段，例如 `$User.Id` 或 `$Organization.Name`。

示例代码

假设我们已经创建了一个名为 `My_API_Service` 的 Named Credential，其 URL 指向 `https://api.example.com`，并配置了密码认证。现在，我们需要调用该服务的 `/invoices/123` 端点来获取发票信息。

以下代码示例严格遵循 Salesforce 官方文档的最佳实践，展示了如何使用 Apex 进行调用。

示例 1: 基本的 GET 请求

此代码展示了最简单直接的调用方式。注意 `setEndpoint` 方法中的 `callout:` 前缀，它告诉 Salesforce 使用我们配置好的 Named Credential。

// Apex Class to make a callout to an external service using a Named Credential

public class InvoiceService {
    public static String getInvoiceData() {
        // 1. 创建一个 HttpRequest 对象
        HttpRequest req = new HttpRequest();

        // 2. 设置端点。'callout:' 语法是关键，它指示 Salesforce
        //    使用名为 'My_API_Service' 的 Named Credential。
        //    '/invoices/123' 是相对于 Named Credential 中配置的基础 URL 的路径。
        req.setEndpoint('callout:My_API_Service/invoices/123');

        // 3. 设置 HTTP 方法为 GET
        req.setMethod('GET');

        // 4. (可选) 设置请求头，例如接受 JSON 格式的响应
        req.setHeader('Accept', 'application/json');

        // 5. 创建一个 Http 对象来发送请求
        Http http = new Http();
        HttpResponse res = null;

        try {
            // 6. 发送请求并获取 HttpResponse 对象
            res = http.send(req);

            // 7. 检查响应状态码
            if (res.getStatusCode() == 200) {
                // 请求成功，返回响应体
                System.debug('Successfully received response: ' + res.getBody());
                return res.getBody();
            } else {
                // 请求失败，记录错误信息
                System.debug('Callout failed. Status: ' + res.getStatus() + ', Status Code: ' + res.getStatusCode());
                System.debug('Response Body: ' + res.getBody());
                return 'Error: ' + res.getStatusCode();
            }
        } catch(System.CalloutException e) {
            // 捕获可能发生的调用异常，例如网络问题或配置错误
            System.debug('Callout exception: ' + e.getMessage());
            return 'Callout Error: ' + e.getMessage();
        }
    }
}

在这个例子中，我们完全不需要在代码中处理用户名、密码或基础 URL。如果 API 的凭证更新了，管理员只需在 Setup 界面更新 Named Credential 配置即可，代码无需任何改动。

注意事项

权限与访问控制

要使用 Named Credential，用户需要相应的权限。在使用新的 External Credential 框架时，管理员必须通过权限集 (Permission Set) 将 `Principal` 授予用户。这意味着我们可以精确控制哪些用户有权通过哪个凭证访问外部系统，这对于实现最小权限原则至关重要。

API 限制 (Governor Limits)

使用 Named Credentials 并不会绕过 Salesforce 的平台限制。每个 Apex 事务中 HTTP 调用的总数（默认为 100 次）和累计超时时间（默认为 120 秒）等限制依然适用。作为集成工程师，在设计解决方案时必须充分考虑这些限制，避免在循环中进行调用，并考虑使用异步处理（如 Queueable Apex 或 Batch Apex）来处理大量数据的集成。

部署与环境管理

Named Credentials、External Credentials 和 Principals 都是元数据，可以通过变更集 (Change Sets) 或 SFDX 进行部署。但是，出于安全原因，密码、客户端密钥 (Client Secret) 等敏感信息不会包含在元数据中进行迁移。这意味着在每次部署到新的环境（如从开发到 UAT，或到生产）后，都需要手动在目标环境中重新输入这些敏感值。这是保障环境安全的关键步骤，必须在部署计划中明确指出。

错误处理

健壮的错误处理是集成工作的生命线。使用 Named Credentials 时，可能会遇到多种错误：

`System.CalloutException`：可能由网络问题、DNS 解析失败或 Named Credential 配置不正确（例如，URL 格式错误）引起。
HTTP 状态码错误：例如 `401 Unauthorized` (认证失败)、`403 Forbidden` (无权访问)、`404 Not Found` (资源不存在) 或 `500 Internal Server Error` (外部服务器错误)。

你的代码必须始终将 `http.send(req)` 调用包裹在 `try-catch` 块中，并仔细检查返回的 `HttpResponse` 的状态码，根据不同的错误类型采取相应的处理逻辑，例如重试、记录日志或通知管理员。

总结与最佳实践

Named Credentials 是 Salesforce 平台提供的用于外部服务集成的基石。它通过将认证细节和端点配置与业务逻辑代码分离，极大地增强了集成的安全性、可维护性和灵活性。对于任何一个 Salesforce 集成工程师来说，熟练掌握 Named Credentials 都是一项必备技能。

最佳实践：

杜绝硬编码：永远不要在 Apex 代码、自定义元数据或任何其他地方硬编码凭证或端点。始终使用 Named Credentials 进行认证调用。
拥抱新框架：对于所有新的集成项目，优先使用基于 External Credential 和 Principal 的现代 Named Credential 框架，以获得更精细的控制和更高的灵活性。
选择正确的身份类型：根据业务需求，仔细选择是为所有用户使用一个共享凭证（`Anonymous`），还是让每个用户使用自己的凭证（`Per User` 或 `Named Principal`）。后者在需要审计追踪到具体用户的场景中非常有用。
规划环境凭证管理：在项目初期就制定好如何在不同环境（Dev, QA, Prod）中管理和配置凭证的策略，避免在上线前手忙脚乱。
编写防御性代码：始终假设调用会失败。实现全面的错误处理和日志记录机制，以便快速定位和解决集成问题。
定期审计：与系统管理员合作，定期审查和轮换外部服务的凭证，确保集成的持续安全。

通过遵循这些原则，我们可以构建出既强大又可靠的 Salesforce 集成解决方案，为企业创造真正的价值。

Salesforce中文网