外部服务异步回调如何工作
外部服务异步操作在 OpenAPI 3.x 兼容规范中通过回调操作进行了描述。异步操作被系统注册为一种特殊类型的可调用操作，允许更长的响应时间。相比之下，外部服务同步操作在 120 秒后超时。对于异步操作，您使用 Apex 定义回调和延迟异步响应的超时。
所需的 Edition
| 适用于：Lightning Experience |
| 适用于：Enterprise、Performance、Unlimited 和 Developer Edition |
备注 Apex 支持外部服务的异步回调操作，但流不支持。
带回调操作的示例 API 规范
该示例 API 规范的特点是虚构公司“Acme Mortgages”的抵押申请流程中的回调操作。回调相关的定义以粗体显示。我们将在本节的其他主题中回到这个示例。
{
"openapi": "3.0.0",
"servers": [{
"url": "/"
}],
"info": {
"version": "1.0",
"title": "Acme Mortgages",
"description": "Acme Mortgages"
},
"paths": {
"/applications": {
"post": {
"operationId": "SubmitApplication",
"description": "Submit a new mortgage application",
"parameters": [{
"name": "callbackUrlForErrorCases",
"in": "query",
"schema": {
"type": "string"
}
}],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"applicant": {
"$ref": "#/components/schemas/Contact"
},
"callbackUrlForOutcomes": {
"type": "object",
"properties": {
"approved": {
"type": "string"
},
"rejected": {
"type": "string"
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Mortgage loan application submission initial response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"applicationNumber": {
"type": "string"
}
}
}
}
}
}
},
"callbacks": {
"applicationOutcomeApproved": {
"$ref": "#/components/callbacks/ApplicationApproved"
},
"applicationOutcomeRejected": {
"$ref": "#/components/callbacks/ApplicationRejected"
},
"applicationError": {
"{$request.query.callbackUrlForErrorCases}": {
"post": {
"parameters": [{
"in": "header",
"name": "applicationNumber",
"schema": {
"type": "string"
}
}],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MortgageApplicationError"
}
}
}
},
"responses": {
"200": {
"description": "Mortgage application callback error accepted"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MortgageApplication": {
"required": [
"applicationNumber",
"status"
],
"properties": {
"applicationNumber": {
"type": "string"
},
"status": {
"description": "One of pending, approved, rejected",
"type": "string"
},
"approvedAmount": {
"type": "number"
}
}
},
"Contact": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
}
}
},
"MortgageApplicationError": {
"properties": {
"errorMessage": {
"type": "string"
},
"applicationNumber": {
"type": "string"
}
}
}
},
"callbacks": {
"ApplicationApproved": {
"{$request.body#/callbackUrlForOutcomes/approved}": {
"post": {
"description": "Application has been approved.",
"operationId": "approvedCallback",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MortgageApplication"
}
}
}
},
"responses": {
"200": {
"description": "Approved application callback result has been retrieved successfully."
}
}
}
}
},
"ApplicationRejected": {
"{$request.body#/callbackUrlForOutcomes/rejected}": {
"post": {
"description": "Application is rejected",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MortgageApplicationError"
}
}
}
},
"responses": {
"200": {
"description": "Rejected application callback result has been retrieved successfully."
}
}
}
}
}
}
}
}
带有异步操作的 Apex 界面示例
在注册时，AcmeMortgages外部服务由外部服务自动呈现在 Apex 中。AcmeMortgages的 Apex 界面出现在“设置”的 Apex 类页面中，如下所示。定义异步操作的附加内容以粗体显示。没有显示动态 Apex 对象，这些对象表示与可调用操作相同的模式对象数据类型。
每个回调由其父级异步操作拥有。唯一的只读回调 URL 由 Salesforce 确定（在第一个标注上）。
global class AcmeMortgages {
// Acme Mortgages SubmitApplication asynchronous operation
global SubmitApplication_Response SubmitApplication(
SubmitApplication_Request input,
SubmitApplication_Callback callback,
DateTime callbackTimeout
) {...}
global class SubmitApplication_Request {
global AcmeMortgages_SubmitApplication_IN_body body {get; set;}
// [REQUEST] Callback URL for asynchronous operation: callbackUrlForErrorCases
global String callbackUrlForErrorCases {get;}
}
// Synchronous response - here getting the application docket number
global class SubmitApplication_Response {
global Integer responseCode {get; set;}
global AcmeMortgages_SubmitApplication_OUT_201 Code201 {get; set;}
// Get invocation ID for this asynchronous response to query callback status
global String invocationId {get;}
}
global class SubmitApplication_ResponseException {
global Integer responseCode {get; set;}
global String defaultResponse {get; set;}
}
// Asynchronous response callback handler for SubmitApplication.
// Each method corresponds to the schema's declared callback key.
// Default implementations throws an exception alerting that a non-implemented callback was called.
global virtual class SubmitApplication_Callback {
global virtual void applicationOutcomeApproved(
List<SubmitApplication_applicationOutcomeApproved_Callback> callbacks) {
throw new SubmitApplication_ResponseException(404,
'Callback not handled: applicationOutcomeApproved');
}
global virtual void applicationOutcomeRejected(List<SubmitApplication_applicationOutcomeRejected_Callback> callbacks) {...}
global virtual void applicationError(List<SubmitApplication_applicationError_Callback> callbacks) {...}
}
// Asynchronous callback response payloads for callback applicationOutcomeApproved
global class SubmitApplication_applicationOutcomeApproved_Callback {
global SubmitApplication_Request request {get; set;}
global DateTime submitTime {get; set;}
global DateTime callbackTimeout {get; set;}
global CallbackStatus callbackStatus {get; set;}
global SubmitApplication_applicationOutcomeApproved_CallbackResponse response {get; set;}
}
global class SubmitApplication_applicationOutcomeApproved_CallbackResponse {
global AcmeMortgages_MortgageApplication body {get; set;}
}
global class SubmitApplication_applicationOutcomeRejected_Callback {...}
global class SubmitApplication_applicationOutcomeRejected_CallbackResponse {...}
global class SubmitApplication_applicationError_Callback {...}
global class SubmitApplication_applicationError_CallbackResponse {...}
}
回调数据流示例
示例
在本例中，一名 Salesforce Apex 开发人员使用外部服务注册了一家银行的抵押贷款申请 API 规范。该规范包含回调操作，因为在申请提交和接受之间预计会有长达一天的延迟。
Apex 开发人员编写带有回调处理程序的 Apex 客户端。Apex 客户端指定在 Salesforce 收到来自外部系统的延迟响应后，Salesforce 使用姓名和其他抵押申请信息的结果列表来自动创建联系人。
此序列图展示了开发人员的 Apex 代码（图中的“Apex客户端/处理程序”）、Salesforce 和银行的抵押贷款申请 API 端点（图中的“外部 Web 服务”）之间的功能数据流。
外部 Web 服务有两个响应。第一个响应是同步的，也是典型的初始 ACK 响应。第二个是异步的延迟响应（从技术上讲是请求），它在请求正文中包含结果有效负载。
首先，Apex 开发人员通过 Apex 客户端向银行服务器（外部服务）发送 HTTP 请求（标注）。
外部 Web 服务立即发回 HTTP 响应，确认收到请求。第一次确认在 120 秒后超时。Salesforce 开发人员可以使用“后台操作”页面或 Apex 调试日志监控请求的状态。
银行启动其内部流程来接收抵押申请、批准或拒绝申请，并最终准备最终结果（在图中显示为“异步延迟”）。
一天后,银行将完成的结果作为 HTTP 请求发送回 Apex 开发人员。抵押申请的结果数据（批准的金额、状态等）包含在请求的正文中。Salesforce 接收结果并根据 Apex 回调处理程序实施对其进行处理。
Salesforce 向外部 Web 服务返回 HTTP 响应确认。如果 Salesforce 成功处理数据（在本例中是创建联系人），则它会向外部 Web 服务发送一个带有 200 状态代码和成功消息的响应。
如果 Salesforce 遇到错误，它会向外部 Web 服务发送 404、408 或 500 状态代码以及一般错误消息。Apex 开发人员可以通过使用后台操作页面或 Apex 调试日志查看更多错误消息详细信息。
本文章是否解决您的问题？
请与我们共享您的想法，以便我们进行改进！
