[レガシー]{class="badge informative"}

Decisioning API を使用したオファーの配信 decisioning-api

TIP
Adobe Journey Optimizer の新しい決定機能である決定が、コードベースのエクスペリエンスチャネルとメールチャネルを通じて使用できるようになりました。 詳細情報

意思決定管理を使用すると、ビジネスロジックと決定ルールを使用し、あらゆるチャネルやアプリケーションをまたいで、パーソナライズされたオファーエクスペリエンスを作成し、エンドユーザーに配信できます。 オファーとは、オファーを表示する資格のあるユーザーを指定するルールが関連付けられているマーケティングメッセージです。

Decisioning API に対して POST リクエストを実行することで、オファーを作成し、配信できます。

このチュートリアルでは、特に意思決定管理に関して、API の実用的な理解が必要です。 詳しくは、意思決定管理 API デベロッパーガイドを参照してください。 このチュートリアルでは、一意のプレースメント ID と決定 ID も必要です。 これらの値を取得していない場合は、プレースメントの作成および決定の作成に関するチュートリアルを参照してください。

NOTE
決定リクエストでのコンテキストデータの受け渡し
決定リクエストでコンテキストデータ(デバイスタイプ、場所、ユーザーの環境設定など)を渡して、動的な実施要件ルールを作成し、リアルタイムの条件に基づいてパーソナライズされたオファーを配信できます。 コンテキストデータと決定リクエストの詳細情報

必須ヘッダー required-headers

次の表に、リクエストヘッダーの Content-Type フィールドと Accept フィールドを構成する有効な値を示します。

ヘッダー名
Accept
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"
Content-Type
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"
認証
Bearer {ACCESS_TOKEN}
x-gw-ims-org-id
{IMS_ORG}
x-sandbox-name
{SANDBOX_NAME}
x-api-key
{API_KEY}
  • ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、content-type ヘッダーが必要です
NOTE
個々のサンドボックスには、権限チェックは適用されません。 呼び出し元が有効なトークンを提示している限り、配信 API は正常に動作します。

API リクエスト request

API 形式

POST /{ENDPOINT_PATH}/decisions
パラメーター
説明
{ENDPOINT_PATH}
リポジトリ API のエンドポイントパス。
https://platform.adobe.io/data/core/ods

リクエスト

curl -X POST 'https://platform.adobe.io/data/core/ods/decisions' \
-H 'Accept: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"' \
-H 'Content-Type: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"' \
-H 'Authorization: Bearer {ACCESS_TOKEN}....' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-sandbox-id: {SANDBOX_ID}' \
-H 'x-request-id: e9ac8d7e-3e77-4b38-8726-555ef1737b32-example' \
-d '{
    "xdm:propositionRequests": [
        {
            "xdm:activityId": "dps:offer-activity:15ded04b1786ea27",
            "xdm:placementId": "dps:offer-placement:15d9bc01d35e1238"
        }
    ],
    "xdm:profiles": [
        {
            "xdm:identityMap": {
                "Email": [
                    {
                        "xdm:id": "example@adobe.com",
                        "primary": true
                    }
                ]
            }
        }
    ],
    "xdm:allowDuplicatePropositions": {
        "xdm:acrossActivities": true,
        "xdm:acrossPlacements": true
    },
    "xdm:responseFormat": {
        "xdm:includeContent": true,
        "xdm:includeMetadata": {
            "xdm:activity": [
                "name"
            ],
            "xdm:option": [
                "name"
            ],
            "xdm:placement": [
                "name"
            ]
        }
    }
}'
プロパティ
説明
xdm:propositionRequests
このオブジェクトには、プレースメント ID と決定 ID が含まれています。
xdm:propositionRequests.xdm:placementId
一意のプレースメント ID。
"xdm:placementId": "dps:offer-placement:ffed0456"
xdm:propositionRequests.xdm:activityId
一意の決定 ID。
"xdm:activityId": "dps:offer-activity:ffed0123"
xdm:itemCount
返されるオファーの数。 最大値は 30 です。
"xdm:itemCount": 2
xdm:profiles
このオブジェクトは、決定がリクエストされるプロファイルに関する情報を保持します。 API リクエストの場合は、プロファイルが 1 つ含まれます。
xdm:profiles.xdm:identityMap
このオブジェクトは、ID の名前空間統合コードに基づく一連のエンドユーザー ID を保持します。 ID マップには各名前空間の複数の ID を保持できます。 名前空間の詳細については、このページを参照してください。
Email: [{"xdm:id": "123@abc.com"}]
xdm:profiles.xdm:decisionRequestId
プロファイルの決定リクエストを一意に識別するために使用できる、クライアントによって生成された ID。 この ID は応答内にエコーバックされ、決定の結果に影響を与えません。
"xdm:decisionRequestId": "0AA00002-0000-1224-c0de-cjf98Csj43"
xdm:allowDuplicatePropositions
このオブジェクトは、重複除外ルールの制御構造を表します。 特定のディメンションに対して同じオプションを提案できるかどうかを示す一連のフラグで構成されます。 フラグを true に設定した場合は、重複が許可され、フラグで示されるカテゴリ全体で削除されません。 フラグを false に設定した場合、決定エンジンはディメンション全体で同じ提案を行わず、代わりにサブデシジョンの 1 つに対して次に最適なオプションを選択する必要があります。
xdm:allowDuplicatePropositions.xdm:acrossActivities
True に設定すると、複数の決定に同じオプションが割り当てられる場合があります。
"xdm:acrossActivities": true
xdm:allowDuplicatePropositions.xdm:acrossPlacements
True に設定すると、複数のプレースメントに同じオプションが割り当てられる場合があります。
"xdm:acrossPlacements": true
xdm:enrichedAudience
カスタムアップロード(CSV)オーディエンスをターゲットにしていて、オファーの決定応答でエンリッチメントデータを取得する場合は、このパラメーターを true に設定します。 決定用の CSV オーディエンスの使用の詳細情報
"xdm:enrichedAudience": true
xdm:mergePolicy.xdm:id
プロファイルアクセスサービスが返すデータを制御する結合ポリシーを指定します。 リクエストで指定されていない場合、意思決定管理はプロファイルアクセスサービスに何も渡さず、指定されている場合は呼び出し元が提供する ID を渡します。
"xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
xdm:responseFormat
応答コンテンツをフォーマットする一連のフラグ。
xdm:responseFormat.xdm:includeContent
ブール値で、true に設定した場合、応答にコンテンツを含めます。
"xdm:includeContent": true
xdm:responseFormat.xdm:includeMetadata
返される追加のメタデータを指定するために使用されるオブジェクト。 このプロパティが含まれていない場合、デフォルトでは xdm:idrepo:etag が返されます。
name
xdm:responseFormat.xdm:activity
このフラグは、xdm:activity に対して返される特定のメタデータ情報を識別します。
name
xdm:responseFormat.xdm:option
このフラグは、xdm:option に対して返される特定のメタデータ情報を識別します。
namecharacteristics
xdm:responseFormat.xdm:placement
このフラグは、xdm:placement に対して返される特定のメタデータ情報を識別します。
namechannelcomponentType

応答

正常な応答では、提案に関する情報(一意の xdm:propositionId を含む)が返されます。

{
  "xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8",
  "xdm:propositions": [
    {
      "xdm:activity": {
        "xdm:id": "dps:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "dps:placement:ffed0456",
        "repo:etag": 1
      },
      "xdm:options": [
        {
          "xdm:id": "dps:personalized-option:ccc0111",
          "repo:etag": 3,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>some html</html>"
        },
        {
          "xdm:id": "dps:personalized-option:ccc0222",
          "repo:etag": 5,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>hello, world</html>",
          "xdm:score": 45.65
        }
      ]
    },
    {
      "xdm:activity": {
        "xdm:id": "dps:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "dps:placement:ffed0789",
        "repo:etag": 2
      },
      "xdm:fallback": {
        "xdm:id": "dps:fallback:ccc0222",
        "repo:etag": 5,
        "@type": "https://ns.adobe.com/experience/decisioning/content-component-imagelink",
        "dc:format": "image/png",
        "xdm:deliveryURL": "https://cdn.adobe.com/content/1445323-1134331.png",
        "xdm:content": "https://www.adobe.com/index2.html"
      }
    }
  ],
  "ode:createDate": 1566497582038
}
プロパティ
説明
xdm:propositionId
XDM DecisionEvent に関連付けられた提案エンティティの一意の ID。
"xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8"
xdm:propositions
このオブジェクトには、決定の提案が 1 つ含まれています。 決定に対して複数のオプションが返されることもあります。 オプションが見つからない場合は、決定のフォールバックオファーが返されます。 1 つの決定の提案には、options プロパティまたは fallback プロパティが常に含まれています。 options プロパティは(存在する場合)、空にすることはできません。
xdm:propositions.xdm:activity
このオブジェクトには、決定の一意の ID が含まれます。
"xdm:id": "dps:activity:ffed0123"
xdm:propositions.xdm:placement
このオブジェクトには、オファープレースメントの一意の ID が含まれます。
"xdm:id": "dps:placement:ffed0456"
xdm:propositions.xdm:options
このオブジェクトには、単一のオプションが含まれます(一意の ID を含む)。 指定する場合、このオブジェクトを空にすることはできません。
xdm:id": "dps:personalized-option:ccc0111
xdm:propositions.xdm:options.@type
コンポーネントのタイプを定義します。 @type は、クライアントの処理契約の役割を果たします。 エクスペリエンスがアセンブルされると、コンポーザーは特定のタイプを持つコンポーネントを探します。
https://ns.adobe.com/experience/offer-management/content-component-imagelink
xdm:propositions.xdm:content
応答コンテンツの形式。
応答コンテンツは、texthtml block、または image link です。
xdm:score
オプションのスコア。オプションのスコアは、オプションまたは決定に関連付けられたランキング関数の計算結果です。 ランク付けの際にオファーのスコアの決定にランキング関数が関与する場合、このフィールドは API から返されます。
"xdm:score": 45.65
xdm:propositions.xdm:fallback
このオブジェクトには、単一のフォールバックオファーが含まれます(一意の ID を含む)。
"xdm:id": "dps:fallback:ccc0222"
xdm:propositions.xdm:fallback.dc:format
リソースの物理的またはデジタル的な表示。 通常、形式にはリソースのメディアタイプを含める必要があります。 形式は、リソースを表示または操作するのに必要なソフトウェア、ハードウェア、または他の機器を決定するために使用できます。 コンピューターメディア形式を定義するインターネットメディアタイプのリストなど、制御された用語から値を選択することをお勧めします。
"dc:format": "image/png" または "image/jpeg"
xdm:propositions.xdm:fallback.xdm:deliveryURL
コンテンツ配信ネットワークまたはサービスエンドポイントからアセットを読み取るためのオプションの URL。 この URL は、ユーザーエージェントからアセットに公開でアクセスするために使用されます。
https://d37yhxrr0p3l3l.cloudfront.net/0fd0f090-a148-11ea-89e3-f1f2ad52f7e8/urn:aaid:sc:US:a68c86a6-9295-4940-a083-11916b665500/0/40d78a12-f8b6-3f07-8e67-7cb8ae2cc7ec
ode:createDate
決定応答メッセージが作成された時間。 これはエポック時間として表されます。
"ode:createDate": 1566497582038

応答コード

次の表に、応答で返されるすべてのコードを示します。

コード
説明
200
成功です。 指定されたアクティビティに対して決定が行われました
400
無効なリクエストパラメーターです。 構文が正しくないため、サーバーがリクエストを認識できません。
403
許可されていません。権限が不十分です。
422
処理できないエンティティです。 リクエストの構文は正しいですが、セマンティックエラーが原因で処理できません。
429
リクエストが多すぎます。 ユーザーが一定の時間に送信したリクエストが多すぎます。
500
内部サーバーエラー。 サーバーで予期しない状況が発生し、リクエストを完了できません。
503
サーバー過負荷のため、サービスを利用できません。 一時的な過負荷のため、サーバーは現在リクエストを処理できません。
NOTE
実装をテストするときは、dryRun フラグを使用してフィードバックイベントを抑制できます。 詳細情報

次の手順 next-steps

この API ガイドに従うことで、Decisions API を使用してオファーを作成し、配信できます。 詳しくは、意思決定管理の概要を参照してください。

recommendation-more-help
journey-optimizer-help