カスタムアクションでの 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"
    

    失敗ペイロードを設定した場合は、そのフィールドの1つに分岐することもできます。 上記の例の場合:

    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

症状
チェック
応答フィールドを使用できません
Response サンプルが有効な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