在自訂動作中使用 API 呼叫回應 custom-action-enhancements

在此頁面上:​擷取自訂動作傳回的JSON回應,並使用其欄位來引導歷程決策、個人化訊息及處理錯誤。

回應裝載需求 custom-action-enhancements-notes

  • 完整回應必須是JSON物件。 不支援做為回應的裸陣列。

  • 陣列可包含在物件中。 支援純量陣列;不支援異質陣列。

支援:

{
  "body": ["val1", "val2"],
  "points": 1290
}

不支援(裸陣列):

["val1", "val2"]

不支援(異質陣列):

{
  "values": [20, "aafw", false]
}

設定自訂動作 config-response

若要擷取自訂動作的回應,請定義端點傳回的裝載範例。

  1. 建立或開啟自訂動作。 請參閱設定自訂動作。

  2. 在​回應 (成功回應)欄位內按一下。

    {width="80%"}

  3. 貼上端點傳回的成功回應範例。 確認範例的欄位型別符合實際回應。 在此範例中,本機端點會傳送熟客點數和設定檔的狀態。

    code language-json
    {
      "customerID": "xY12hye",
      "status": "gold",
      "points": 1290
    }
    

    {width="80%"}

    範例會定義Journey Optimizer每次呼叫動作時擷取的欄位。

  4. (選擇性)若要擷取失敗承載,請選取​定義失敗回應承載,並提供符合呼叫失敗時端點傳回之承載的範例。 例如:

    code language-json
    {
      "message": "customer not found"
    }
    

    設定後,可在errorResponse節點下使用失敗裝載欄位。 範例的形狀應與實際的失敗回應相符。

  5. 新增任何必要的請求引數。 在此範例中,customerID是查詢引數。

    {width="80%"}

  6. 按一下「儲存」。

在歷程中使用回應 response-in-journey

將自訂動作新增至歷程。 然後,您可以在條件、後續動作和訊息個人化中使用回應欄位。

例如,您可以新增條件以檢查熟客點數。 當人員進入餐廳時,您的本機端點會傳送包含設定檔忠誠度資訊的呼叫。 如果設定檔為黃金客戶,則可傳送推播。 如果在呼叫中偵測到錯誤,請傳送自訂動作以通知您的系統管理員。

  1. 新增您的事件和先前建立的熟客方案自訂動作。

  2. 在忠誠度自訂動作中,對應必要的輸入引數,例如具有設定檔ID的客戶ID查詢引數。 選取​ 在逾時或錯誤的情況下新增替代路徑 ​以分別處理這些結果。

  3. 在成功路徑中,新增條件並使用動作回應欄位。 在進階編輯器中,Context​節點下有可用的回應欄位。

  4. 新增推播或其他動作,並使用回應欄位個人化您的訊息。 在此範例中,內容會使用熟客點數和客戶狀態。 回應欄位位於​內容屬性 > Journey Orchestration > 動作​下。

    note
    NOTE
    即使端點針對每個設定檔傳回相同的回應,輸入自訂動作的每個設定檔都會觸發呼叫。
  5. 在逾時和錯誤路徑中,新增條件並使用內建​ jo_status_code ​欄位在呼叫結果上分支。 在此範例中,條件會檢查​ http_400 ​錯誤型別。 檢視錯誤狀態。

    code language-none
    @action{ActionLoyalty.jo_status_code} == "http_400"
    

    如果您已設定失敗裝載,也可以在其其中一個欄位上分支。 以上例為例:

    code language-none
    @action{ActionLoyalty.errorResponse.message} == "customer not found"
    

  6. 新增自訂動作以通知您的組織。

測試模式記錄 test-mode-logs

使用測試模式來檢查記錄檔中​ actionsHistory ​區段中的動作傳回的裝載。 對於失敗的呼叫,記錄檔會包含失敗裝載(若已設定)。 這對於偵錯很有用。

錯誤狀態 error-status

jo_status_code​欄位可供使用,即使未定義回應裝載亦然。 可能的值包括:

值
含義
http_<code>
API呼叫傳回的HTTP狀態代碼,例如http_200或http_400
timedout
呼叫逾時
capped
已透過上限封鎖呼叫
internalError
發生內部錯誤

當傳回的HTTP程式碼大於2xx或發生其他錯誤時,會將動作呼叫視為錯誤。 在這種情況下,歷程會遵循設定的逾時或錯誤分支。

依照預設,只有新建立的自訂動作包含​ jo_status_code ​欄位。 若要搭配現有自訂動作使用,請更新並儲存動作。 例如,您可以更新其說明。

如果未設定失敗回應承載,errorResponse節點將不可用。

運算式語法 exp-syntax

參考回應欄位,其中包含:

@action{<action name>.<field path>}

例如:

@action{ActionLoyalty.status}

若要提供預設值,請執行下列動作:

@action{<action name>.<field path>, defaultValue: <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

在支援的原生管道個人化(電子郵件、推播、行動訊息)中使用自訂動作回應欄位。 如需陣列和巢狀資料,請參閱使用Handlebars反複處理內容資料。

疑難排解 troubleshooting

症狀
檢查
回應欄位無法使用
確認​ 回應 ​範例是有效的JSON,並反映端點的回應結構和欄位型別。
無法使用回應,因為它是陣列
請改為傳回物件,並將陣列放置在欄位中。
有些陣列值無法使用
確認陣列並非異質性。
現有動作上缺少jo_status_code
更新並儲存動作。 預設情況下,僅新建立的動作會包含欄位。
errorResponse無法使用
設定並儲存失敗回應裝載。
呼叫會在逾時或錯誤分支後進行
檢查jo_status_code並在測試模式記錄檔中檢查失敗承載(若已設定)。

其他資源

AI Knowledge Reference

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:

  • The response payload must be a JSON object; a bare top-level array as the whole response is not supported, so place the array inside a field (for example body).
  • 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: Can the whole custom action response be an array? — No; the response payload must be a JSON object, so place the array inside a field (for example body). A bare top-level array as the whole response is not supported. 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, mobile messages) for message personalization.

Personas:

developer: Can leverage API call response payload fields in conditions, other actions, and message personalization. Can reference action response fields using the expression syntax, for example @action{ActionLoyalty.status}. Can use currentActionField to access the current item while manipulating a collection in a custom action response. Where: “Expression syntax”. admin: Can configure the custom action by pasting an example payload into the Response field to capture fields returned by the call. Can enable an error response payload by selecting Define a failure response payload in the custom action configuration. The page states that only newly created custom actions include the jo_status_code field out-of-the-box. Where: “Configure the custom action”.

Onboarding:

Level: Experienced First minimal step: Paste an example of the payload returned by the call. Success check: Each time the API is called, the system retrieves all the fields included in the payload example. Previous: Before configuring the response payload, create the custom action: Configure a custom action (action/about-custom-action-configuration.md) Next: To iterate over arrays and nested data from the response in messages: Iterate over contextual data (personalization/iterate-contextual-data.md)`

``

recommendation-more-help
journey-optimizer-help