为外部服务定义 API 规范

学习目标

完成本单元后，您将能够：

描述 API 规格的用途。
解释支持的外部服务模式定义的元素。
列举三个可能导致 API 规格失败的问题。

为什么需要模式定义？

在上一单元中，您了解到 API 规范是一份文件，其中包含定义 API 功能的描述性模式。无论您是否最终要为外部服务注册创建 API 规范，了解其用途和使用方式都对您有帮助。

假设您有一个基于 REST 的银行 API。您需要一个通用的标准化格式来描述银行基于 REST 的 API 结构。输入 API 规格。Salesforce 采用常用的 OpenAPI 规范作为描述格式。

您的 API 规范包含一个模式定义，该定义描述了在您的组织对外部 Web 服务的调用或请求中可以包含的输入输出类型。例如：您的调用可能包括一个 ID 作为数字输入或包含一个 name 作为文本输出。

API 规格还包含可访问的基于 REST 的 API Web 服务端点信息与身份验证参数。（请记住：端点显示外部服务与之交互的 Web 服务资源。）例如：该虚拟银行 Web 服务的 API 规范包括添加、删除银行帐户的方法。https://th-external-services.herokuapp.com/accounts/schema

在真实的应用程序中，按安全最佳实践，访问银行 API 之前需要进行身份验证。

因为虚构银行的 API 规范是用户可读的结构化数据，我们一起来看看。

下面是模式的基本帐户操作。

操作路径：/accounts/{accountName}	描述
GET	检索一个帐户
POST	添加一个帐户
PUT	更新一个帐户
DELETE	删除一个帐户

下面是来自 API 规格模式的部分代码片段，其中包含关于获取方法的信息。解释一下，获取方法就是从 Web 服务中检索资源信息。此特定的 GET 方法利用资源路径检索 (“gets”) 帐户信息，在本个案中是 /accounts/{accountName}，其中 {accountName} 为指定帐户。如果您在 parameters” 下查看，您可以看到 "name":"accountName"。该参数必须与您指定的帐户名匹配，且为必填 ("required":true)。该参数还应采用字符串形式。

"paths": {
	"/accounts/{accountName}": 
	{ "get": 
		{ "operationId": "getAccount", 
		"summary": "Retrieves an account", 
		"description": "Retrieves the account with specific name",
		"consumes": ["text/plain"], 
		"produces": ["application/json"], 
		"parameters": [{ 
		"name": "accountName", 
		"in": "path", 
		"required": true, 
		"type": "string", 
		"description": "Name of the account" }], 
		"responses": { 
			"200": { 
				"description": "The response when system finds an account with given name", 
				"schema": { 
				"$ref": "#/definitions/accountDetails" } }, "400": 
				{ "description": "Error response if the account name parameter is less than minimum characters",
			"schema": 
			{ "$ref": "#/definitions/errorModel" } }, 
			"404": { 
			"description": "Error response if the account is not supported by service or account is not found",
			"schema": { "
			$ref": "#/definitions/errorModel" 
			}

这只是模式定义的一小部分。但您可以看到，虽然它是为外部服务使用而设计，但也是用户可读的。它还以一种逻辑方式格式化，允许外部服务处理操作，从而可以在 Flow Builder 或 Einstein Bot 等工具中将它们作为可调用的操作显示出来。

接下来将向您展示如何以声明方式注册 API 规格。但首先，让我们探讨构成有效且受支持的模式定义的元素——API 规范文档中包含的各独立 API 功能详细描述。

哪些东西构成一个有效且受支持的模式？

现在我们已了解 API 规格。但我们所说的有效的、受支持的模式是什么意思呢？

有 OpenAPI 规格定义的模式验证要求，也有特定的外部服务模式要求。当这两个要求都得到满足时，外部服务可以正确地支持您的模式并调用您的 Web 服务。

模式验证概要

虽然模式为人可读，但也必须是机器可读的。模式需遵循逻辑结构，以便外部服务能轻松采用。结构不正确的模式意味着外部 Web 服务无法通信（返回错误和异常消息），最终，外部服务无法吸收它。满足结构、逻辑和语法的限制是模式验证的第一步。OpenAPI 规格定义了这些通用规则，并在调用外部 Web 服务时进行了猜测。

受支持的外部服务模式

除模式验证通用 OpenAPI 指南外，还有特定于外部服务的模式限制。外部服务注册 API 规格前，您需检查一下此类要求。外部服务中受支持的模式指的是：根据 OpenAPI 规范，您的模式有效，且模式符合特定外部服务要求。例如：如 API 规格超过文件大小限制，或超过对象或操作总数限制，则可能会注册失败。

有关创建外部服务支持模式的关键需求列表，请参见 Salesforce 帮助：外部服务注意事项。