在此页面上：捕获自定义操作的API调用返回的响应有效负载，以便根据来自外部系统的数据编排历程、个性化消息和处理错误。
您可以在自定义操作中利用API调用响应，并根据这些响应编排历程。
重要说明 custom-action-enhancements-notes
-
响应有效负载支持标量数组：
code language-none "dummyScalarArray": [ "val1", "val2" ] -
响应有效负载中不支持异构阵列：
code language-none "dummyRandomArray": [ 20, "aafw", false ]
配置自定义操作 config-response
-
创建自定义操作。 请参见此页面。
-
在响应（成功响应）字段中单击。
-
粘贴由调用返回的有效负载示例。 验证字段类型是否正确（字符串、整数等）。 以下是调用期间捕获的响应有效负载示例。 我们的本地端点发送会员积分数和用户档案的状态。
code language-none { "customerID" : "xY12hye", "status":"gold", "points": 1290 }
每次调用 API 时，系统将检索有效负载示例中包含的所有字段。
-
（可选）启用错误响应有效负载以捕获调用失败时返回的格式，然后粘贴示例有效负载。 为此，请在自定义操作配置中选择定义失败响应有效负载。 在配置自定义操作中了解有关配置有效负载字段的更多信息。
code language-none { "errorResponse" : "customer not found" }只有在自定义操作配置中启用错误响应有效负载时，该有效负载才可用。
-
我们还要将customerID添加为查询参数。
-
单击保存。
在历程中利用响应 response-in-journey
只需将自定义操作添加到历程中。 然后，您可以在条件、其他操作和消息个性化中利用响应有效负载字段。
如果您定义了错误响应有效负载，则该有效负载将显示在上下文属性 > Journey Orchestration > 操作 > <action name> > errorResponse下。 您可以在超时和错误分支中使用它来驱动回退逻辑和错误处理。
例如，您可以添加条件以检查会员积分数。 当人员进入餐厅时，您的本地端点会发送包含用户档案忠诚度信息的调用。 如果用户档案是黄金客户，则可以发送推送。 如果在调用中检测到错误，请发送自定义操作以通知您的系统管理员。
-
添加您的事件和之前创建的忠诚度自定义操作。
-
在“忠诚度”自定义操作中，将客户ID查询参数映射到配置文件ID。 选中选项在超时或错误的情况下添加替代路径。
-
在第一个分支中，添加条件并使用高级编辑器利用 Context 节点下的操作响应字段。
-
然后，添加推送，并使用响应字段个性化消息。 在本例中，我们使用忠诚度积分数和客户状态来个性化内容。 操作响应字段在上下文属性 > Journey Orchestration > 操作下可用。
note NOTE 每个输入自定义操作的配置文件都将触发调用。 即使响应始终相同，历程仍会为每个配置文件执行一个调用。 -
在超时和错误分支中，添加条件并利用内置 jo_status_code 字段。 在我们的示例中，我们使用
http_400错误类型。 请参阅此小节。code language-none @action{ActionLoyalty.jo_status_code} == "http_400"如果定义了错误响应有效负载，则还可以定位其字段，例如：
code language-none @action{ActionLoyalty.errorResponse.errorResponse} == "customer not found"
-
添加将发送到贵组织的自定义操作。
测试模式日志 test-mode-logs
您可以通过测试模式访问与自定义操作响应相关的状态日志。 如果您在历程中定义了具有响应的自定义操作，您将在这些日志中看到 actionsHistory 部分，其中显示外部端点返回的有效负载（作为来自该自定义操作的响应）。 定义错误响应有效负载后，它将包含在失败的调用中。 这在调试方面可能非常有用。
错误状态 error-status
jo_status_code字段始终可用，即使未定义响应有效负载也是如此。
以下是此字段的可能值：
- http状态代码： http_
<HTTP API call returned code>，用于实例http_200或http_400 - 超时错误：timedout
- 上限设置错误： 上限
- 内部错误： 内部错误
如果返回的http代码大于2xx或发生错误，则认为操作调用有误。 在这种情况下，历程会流向专用超时或错误分支。
如果为自定义操作配置了错误响应有效负载，则其字段在失败调用的 errorResponse 节点下公开。 如果未配置错误响应有效负载，则该节点不可用。
表达式语法 exp-syntax
以下是语法：
#@action{myAction.myField}
下面是一些示例：
// action response field
@action{<action name>.<path to the field>}
@action{ActionLoyalty.status}
// action response field
@action{<action name>.<path to the field>, defaultValue: <default value expression>}
@action{ActionLoyalty.points, defaultValue: 0}
@action{ActionLoyalty.points, defaultValue: @event{myEvent.newPoints}}
在自定义操作响应中处理收藏集时，您可以依赖currentActionField来访问当前项：
count(
@action{MyAction.MyCollection.all(
currentActionField.description == "abc"
)}
)
在本机渠道中使用自定义操作响应 response-in-channels
自定义操作的响应有效负载字段可用于消息个性化的本机渠道（电子邮件、推送、短信）。 这包括迭代外部API返回的数组和嵌套数据结构的功能。
有关迭代消息中的自定义操作响应数据的详细示例和语法，请参阅使用Handlebars迭代上下文数据。
其他资源
有关更多信息，请参阅以下页面：
This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.
For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.
- TL;DR: This page explains how to capture the response payload returned by a custom action’s API call and leverage it to orchestrate journeys, personalize messages, and handle errors.
Intents:
- Configure a custom action to capture success and failure response payloads
- Leverage response payload fields in conditions, other actions, and message personalization
- Handle errors and timeouts using the jo_status_code field and the errorResponse node
- Inspect custom action responses through test mode logs
- Use the expression syntax to reference response fields, including default values and collections
Glossary:
- Response payload: The example payload pasted in the Response (success response) field whose fields are retrieved on each call (product-specific)
- Error response payload: The payload captured when a call fails, enabled by selecting Define a failure response payload, exposed under the errorResponse node (product-specific)
- jo_status_code: A built-in field, always available even when no response payload is defined, that carries the call outcome (product-specific)
- actionsHistory: A section shown in test mode logs that displays the payload returned by the external endpoint (product-specific)
- currentActionField: A reference used to access the current item when manipulating collections in a custom action response (product-specific)
- Test mode: The mode through which you access status logs related to custom action responses (product-specific)
Guardrails:
- Scalar arrays are supported in the response payload, but heterogeneous arrays are not supported.
- Only newly created custom actions include the jo_status_code field out-of-the-box; to use it with an existing custom action you need to update the action, for example by updating the description and saving.
- An action call is considered in error when the returned http code is greater than 2xx or if an error occurs, and the journey flows to the dedicated timeout or error branch.
- If an error response payload is configured, its fields are exposed under the errorResponse node for failed calls; if none is configured, that node is not available.
- Each profile entering the custom action triggers one call, even if the response is always the same.
Terminology:
- Canonical name: API call response in custom actions — Acronym: n/a — variants: custom action response, response payload
- Synonyms: “success response” = “Response field”
- Do not confuse: “Response” (success response payload) ≠ “Error Response” (failure response payload defined via Define a failure response payload)
- jo_status_code values: http_
(for example http_200 or http_400), timedout (timeout error), capped (capping error), internalError (internal error)``
`FAQ:
Q: Which array types are supported in the response payload? — Scalar arrays are supported; heterogeneous arrays are not supported. Q: Why does an existing custom action not expose the jo_status_code field? — Only newly created custom actions include it out-of-the-box; update the existing action, for example by updating the description and saving, to add it. Q: When is an action call considered in error? — When the returned http code is greater than 2xx or an error occurs, after which the journey flows to the dedicated timeout or error branch. Q: Where can the returned payload be inspected? — Through test mode logs, in the actionsHistory section that displays the payload returned by the external endpoint. Q: Can response payload fields be used in native channels? — Yes, response payload fields from custom actions can be used in native channels (email, push, SMS) for message personalization.`
``