メッセージ変換テンプレートの作成とテスト create-template
概要 overview
Destination SDK の一部として、アドビは、宛先の設定およびテストを支援するためのデベロッパーツールを提供しています。このページでは、メッセージ変換テンプレートの作成およびテスト方法を説明します。宛先のテスト方法について詳しくは、宛先設定のテストを参照してください。
Adobe Experience Platform のターゲットスキーマと宛先でサポートされているメッセージ形式の間で メッセージ変換テンプレートを作成およびテスト するには、後述する テンプレートオーサリングツール を使用します。ソースおよびターゲットスキーマ間のデータ変換について詳しくは、メッセージ形式ドキュメントを参照してください。
以下の図に、メッセージ変換テンプレートの作成およびテストが Destination SDK の宛先設定ワークフローにどのように適合するかを示します。
メッセージ変換テンプレートの作成とテストが必要な理由 why-create-message-transformation-template
Destination SDK で宛先を作成する最初の手順のひとつは、Adobe Experience Platform から宛先に書き出される際に、オーディエンスメンバーシップ、ID、プロファイル属性のデータ形式がどのように変換されるかを考慮することです。Adobe XDM スキーマと宛先スキーマとの間の変換について詳しくは、メッセージ形式ドキュメントを参照してください。
変換を成功させるためには、セグメント、ID およびプロファイル属性を送信するテンプレートの作成の例に類似した変換テンプレートを提供する必要があります。
アドビは、Adobe XDM 形式から宛先でサポートされている形式にデータを変換するメッセージテンプレートを作成およびテストできる、テンプレートツールを提供しています。ツールには、以下に使用できる 2 つの API エンドポイントがあります。
- サンプルテンプレート API を使用して、サンプルテンプレートを取得する。
- レンダリングテンプレート API を使用して、サンプルテンプレートをレンダリングする。これにより、結果を宛先で想定されているデータ形式と比較できます。書き出されたデータを宛先で想定されるデータ形式と比較したら、テンプレートを編集できます。この方法で、生成する書き出されたデータを、宛先で想定されるデータ形式に一致させます。
テンプレート作成前に完了すべき手順 prerequisites
テンプレート作成の準備を整える前に、必ず以下の手順を完了してください。
-
宛先サーバー設定を作成します。生成するテンプレートは、
maxUsersPerRequestパラメーターに指定した値に基づいて異なります。- 宛先への API 呼び出しに、単一のプロファイルと、そのオーディエンスの選定、ID およびプロファイル属性を含めたい場合は、
maxUsersPerRequest=1を使用します。 - 宛先への API 呼び出しに、複数のプロファイルと、そのオーディエンスの選定、ID およびプロファイル属性を含めたい場合は、1 より大きな値を持つ
maxUsersPerRequestを使用します。
- 宛先への API 呼び出しに、単一のプロファイルと、そのオーディエンスの選定、ID およびプロファイル属性を含めたい場合は、
-
宛先設定を作成して、宛先サーバー設定の ID を
destinationDelivery.destinationServerIdに追加します。 -
先ほど作成した宛先設定の ID を取得して、テンプレート作成ツールで使用します。
-
メッセージ変換テンプレートで使用できるのはどの関数およびフィルターかを理解します。
サンプルテンプレート API およびレンダリングテンプレート API を使用した、宛先用のテンプレートの作成 iterative-process
"template": "{% for profile in input.profiles %}{{profile|raw}}{% endfor %}}"テンプレートを取得およびテストするプロセスは、反復されます。書き出されたプロファイルが宛先で想定されているデータ形式に一致するまで、以下の手順を繰り返します。
- 最初に、サンプルテンプレートを取得します。
- サンプルテンプレートを出発点として使用し、独自のドラフトを作成します。
- 独自のテンプレートを使用して、レンダリングテンプレート API エンドポイントを呼び出します。アドビは、スキーマに基づいてサンプルプロファイルを生成し、結果または発生したエラーを返します。
- 書き出されたデータを宛先で想定されるデータ形式と比較します。必要に応じて、テンプレートを編集します。
- 書き出されたプロファイルが宛先で想定されているデータ形式に一致するまで、このプロセスを繰り返します。
サンプルテンプレート API を使用したサンプルテンプレートの取得 sample-template-api
以下に示すように、呼び出しに宛先 ID を追加すると、応答は、宛先 ID に対応するテンプレートの例を返します。
curl --location --request GET 'https://platform.adobe.io/data/core/activation/authoring/testing/template/sample/5114d758-ce71-43ba-b53e-e2a91d67b67f' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: {API_KEY}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
指定する宛先 ID が、ベストエフォート集計と集計ポリシーの maxUsersPerRequest=1 を含む宛先設定に対応する場合、リクエストは、以下に類似したサンプルテンプレートを返します。
{#- THIS is an example template for a single profile -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
"identities": [
{%- for idMapEntry in input.profile.identityMap -%}
{%- set namespace = idMapEntry.key -%}
{%- for identity in idMapEntry.value %}
{
"type": "{{ namespace }}",
"id": "{{ identity.id }}"
}{%- if not loop.last -%},{%- endif -%}
{%- endfor -%}{%- if not loop.last -%},{%- endif -%}
{% endfor %}
],
"AdobeExperiencePlatformSegments": {
"add": [
{%- for segment in input.profile.segmentMembership.ups | added %}
"{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
{% endfor %}
],
"remove": [
{#- Alternative syntax for filtering audiences by status: -#}
{% for segment in removedSegments(input.profile.segmentMembership.ups) %}
"{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
{% endfor %}
]
}
}
指定する宛先 ID が、設定可能な集計またはベストエフォート集計を含み、maxUsersPerRequest が 1 より大きい宛先サーバーテンプレートに対応する場合、リクエストは、以下に類似したサンプルテンプレートを返します。
{#- THIS is an example template for multiple profiles -#}
{#- A '-' at the beginning or end of a tag removes all whitespace on that side of the tag. -#}
{
"profiles": [
{%- for profile in input.profiles %}
{
"identities": [
{%- for idMapEntry in profile.identityMap -%}
{%- set namespace = idMapEntry.key -%}
{%- for identity in idMapEntry.value %}
{
"type": "{{ namespace }}",
"id": "{{ identity.id }}"
}{%- if not loop.last -%},{%- endif -%}
{%- endfor -%}{%- if not loop.last -%},{%- endif -%}
{% endfor %}
],
"AdobeExperiencePlatformSegments": {
"add": [
{%- for segment in profile.segmentMembership.ups | added %}
"{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
{% endfor %}
],
"remove": [
{#- Alternative syntax for filtering audiences by status: -#}
{% for segment in removedSegments(profile.segmentMembership.ups) %}
"{{ segment.key }}"{%- if not loop.last -%},{%- endif -%}
{% endfor %}
]
}
}{%- if not loop.last -%},{%- endif -%}
{% endfor %}
]
}
テンプレートの文字をエスケープ character-escape-template
テンプレートを使用して、宛先の想定される形式に一致するプロファイルをレンダリングする前に、以下の画面録画に示すように、テンプレートの文字をエスケープする必要があります。
オンライン文字エスケープツールを使用できます。上記のデモでは、JSON Escape formatter を使用しています。
レンダリングテンプレート API render-template-api
サンプルテンプレート API を使用してメッセージ変換テンプレートを作成したら、テンプレートをレンダリングし、それに基づいて、書き出されたデータを生成できます。これにより、Adobe Experience Platform が宛先に書き出すプロファイルが宛先の想定される形式に一致するかどうかを検証できます。
実行できる呼び出しの例については、API リファレンスを参照してください。
書き出されたプロファイルが宛先で想定されているデータ形式に一致するまで、テンプレートを編集して、レンダリングテンプレート API エンドポイントへの呼び出しを行います。
文字がエスケープされたテンプレートの宛先サーバー設定への追加
メッセージ変換テンプレートに満足したら、宛先サーバー設定の httpTemplate.requestBody.value に追加します。