カスタムアクションでの API 呼び出し応答の使用 custom-action-enhancements
カスタムアクションで 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 クエリパラメーターをマッピングします。 「タイムアウトまたはエラーの場合に代替パスを追加」オプションをオンにします。
-
1 つ目の分岐で、条件を追加し、高度なエディターを使用して、「コンテキスト」ノードの下にあるアクション応答フィールドを活用します。
-
次に、プッシュを追加し、応答フィールドを使用してメッセージをパーソナライズします。 この例では、ロイヤルティポイント数と顧客ステータスを使用してコンテンツをパーソナライズします。 アクション応答フィールドは、コンテキスト属性／Journey Orchestration／アクションで使用できます。
note NOTE 各プロファイルがカスタムアクションに入ると、呼び出しをトリガーします。 応答が常に同じであっても、ジャーニーはプロファイルごとに 1 回の呼び出しを実行します。 -
タイムアウトとエラーのブランチで、条件を追加し、組み込みのjo_status_code フィールドを活用します。この例では、Adobe Analyticsの
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
カスタムアクション応答に関連するステータスログに、テストモードでアクセスできます。 ジャーニーに応答を含むカスタムアクションを定義している場合は、（そのカスタムアクションからの応答として）外部エンドポイントから返されたペイロードを表示するログの「アクション履歴」セクションが表示されます。 エラー応答ペイロードが定義されると、失敗した呼び出しに対して含まれます。 これは、デバッグの面で非常に役立つ場合があります。
エラーステータス error-status
jo_status_code フィールドは、応答ペイロードが定義されていない場合でも常に使用できます。
このフィールドに指定できる値は次のとおりです。
- http ステータスコード：http_
<HTTP API call returned code>、例えば、http_200 や http_400 - タイムアウトエラー：timedout
- キャップエラー：capped
- 内部エラー：internalError
返された 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
カスタムアクションからの応答ペイロードフィールドは、メッセージのパーソナライゼーション用にネイティブチャネル（メール、プッシュ、SMS）で使用できます。 これには、外部 API によって返される配列やネストされたデータ構造を反復処理する機能が含まれます。
メッセージ内のカスタムアクション応答データを繰り返す例と構文について詳しくは、Handlebarsを使用したコンテキストデータの繰り返しを参照してください。
その他のリソース
詳しくは、次のページを参照してください。