APIを使用した外部オーディエンスの作成とアクティブ化

このチュートリアルでは、Adobe Experience Platform APIを使用して外部オーディエンスを作成するために必要な手順について説明します。

はじめに

このチュートリアルでは、外部オーディエンスの作成に関連する様々なExperience Platform サービスについて理解する必要があります。 このチュートリアルを開始する前に、次のサービスに関するドキュメントを参照してください。

必須ヘッダー

このチュートリアルでは、Experience Platform APIへの呼び出しを正常に行うには、認証チュートリアル ​を完了している必要もあります。 次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Experience Platform APIへのリクエストには、操作を行うサンドボックスの名前を指定するヘッダーが必要です：

すべての POST、PUT、および PATCH リクエストには、次の追加ヘッダーが必要です。

外部オーディエンスの準備 prepare

Experience Platform内で外部オーディエンスを作成する前に、オーディエンスデータを含むファイルを準備する必要があります。

この例では、CSV ファイルを使用する必要があります。 CSV ファイルに、ECID、電子メール ID、CRM IDなどのID値を持つ​ 少なくとも ​つの列が含まれていることを確認します。 さらに、セグメンテーションやアクティベーションに必要な、あらゆるエンリッチメント属性を含める必要があります。

また、ファイルがExperience Platform スキーマの要件に準拠していることを確認する必要があります。 スキーマの作成について詳しくは、APIを使用したスキーマの作成に関するチュートリアルまたはUIを使用したスキーマの作成に関するチュートリアルを参照してください。

CSV ファイルに必要なすべての情報が含まれており、スキーマに準拠していることを確認したら、ソースを使用してデータをExperience Platformに取り込むために、CSV ファイルをクラウドストレージプロバイダーにアップロードする必要があります。 クラウドストレージソースの使用について詳しくは、🔗APIを使用したクラウドストレージオプションの探索に関するチュートリアルまたは​ ソースの概要を参照してください。

外部オーディエンスの作成 create

CSV ファイルを準備したら、外部オーディエンスの作成プロセスを開始できるようになりました。

/external-audience/ エンドポイントにPOST リクエストを行うことで、外部オーディエンスを作成できます。

このリクエストを行う際には、次の情報を指定する必要があります。

このエンドポイントの使用方法について詳しくは、外部オーディエンスエンドポイントガイド ​を参照してください。

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/ \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": "40",
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }'

このリクエストを行った後、応答から受け取ったoperationIdに注意して、オーディエンス IDを取得できるようにしてください。

オーディエンス IDの取得 retrieve-audience-id

外部オーディエンスを作成したら、オーディエンスをExperience Platformに取り込むためにオーディエンス IDを取得する必要があります。

オーディエンス IDを取得するには、/external-audiences/operations エンドポイントに対してGET リクエストを行い、以前に作成した外部オーディエンス応答から受け取った操作のIDを指定します。

このエンドポイントの使用方法について詳しくは、外部オーディエンスエンドポイントガイド ​を参照してください。

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/{OPERATION_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

このリクエストを行った後、応答から受け取ったaudienceIdに注意して、オーディエンスの取り込みジョブをトリガーできるようにしてください。

オーディエンス収集を開始 start-ingestion

audienceIdが完成したので、外部オーディエンスのExperience Platformへの取り込みをトリガーできるようになりました。

オーディエンス IDを指定しながら、次のエンドポイントにPOST リクエストを実行することで、オーディエンスの取り込みを開始できます。 さらに、どのファイルが処理されるかを決定するには、開始時間を指定する必要があります。

このエンドポイントの使用方法について詳しくは、外部オーディエンスエンドポイントガイド ​を参照してください

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
    "dataFilterStartTime": 764245635
 }'

このリクエストを行った後、取り込みステータスを監視できるように、応答から受け取ったrunIdを必ずメモしてください。

取り込みステータスの監視 monitor-ingestion

オーディエンスの取り込みをトリガーした後、取り込みの進行状況を監視して、取り込みの成功を確認し、ダウンストリームのアクティベーションに対するオーディエンスの可用性を検証できるようになりました。

オーディエンス IDと実行IDの両方を指定しながら、次のエンドポイントにGET リクエストを実行することで、オーディエンス取り込みのステータスを取得できます。

このエンドポイントの使用方法について詳しくは、外部オーディエンスエンドポイントガイド ​を参照してください。

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs/{RUN_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

次の手順 next-steps

外部オーディエンスが正常に取り込まれたことを確認したら、オーディエンスポータルで確認し、宛先などのダウンストリームサービスで使用できます。

オーディエンスポータルについて詳しくは、​ オーディエンスポータル UI ガイド ​を参照してください。 宛先について詳しくは、宛先の概要を参照してください。