API を使用したデータセットのプロファイル更新の有効化

このチュートリアルでは、リアルタイム顧客プロファイルデータを更新するために、「アップサート」機能によってデータセットを有効にするプロセスについて説明します。 これには、新しいデータセットを作成し、既存のデータセットを設定する手順が含まれます。

はじめに

このチュートリアルでは、プロファイル対応データセットに関連する様々な Adobe Experience Platform サービスに関する十分な知識が必要です。このチュートリアルを開始する前に、これらの関連 Platform サービスに関するドキュメントを確認してください。

以下の節では、Platform API を正しく呼び出すために知っておく必要がある追加情報を示します。

API 呼び出し例の読み取り

このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。

必須ヘッダーの値の収集

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

ペイロード（POST、PUT、PATCH）を含むすべてのリクエストには、追加の Content-Type ヘッダーが必要です。必要に応じて、このヘッダーの正しい値がサンプルリクエストに表示されます。

Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。Platform API へのすべてのリクエストには、操作が行われるサンドボックスの名前を指定する x-sandbox-name ヘッダーが必要です。Platform のサンドボックスについて詳しくは、サンドボックスの概要に関するドキュメントを参照してください。

プロファイル更新が有効なデータセットの作成

新しいデータセットを作成する際に、そのデータセットのプロファイルを有効にし、作成時に更新機能を有効にできます。

プロファイルおよび更新を有効化したデータセットを作成するには、/dataSets エンドポイントに POST リクエストを使用します。

API 形式

POST /dataSets

リクエスト

リクエスト本文で、tags の下に unifiedIdentity と unifiedProfile の両方を含めることで、作成時に Profile を有効にしたデータセットになります。unifiedProfile 配列内で isUpsert:true を追加することで、データセットに更新をサポートする機能が追加されます。

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'

応答

正常に完了すると、新しく作成されたデータセットの ID を含む配列が、"@/dataSets/{DATASET_ID}"の形式で表示されます。

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

既存のデータセットの設定 configure-an-existing-dataset

次の手順では、既存のプロファイルを有効にしたデータセットを更新（アップサート）機能用に設定する方法を説明します。

データセットがプロファイルに対して有効かどうかを確認

Catalog API を使用すると、既存のデータセットを調べて、そのデータセットが Real-Time Customer Profile での使用に対して有効になっているかどうかを判断できます。 次の呼び出しは、データセットの詳細を ID によって取得します。

API 形式

GET /dataSets/{DATASET_ID}

リクエスト

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "{SCHEMA}",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

tags プロパティの下で、unifiedProfile の値が enabled:true となっていることがわかります。したがって、Real-Time Customer Profile はこのデータセットに対して有効になっています。

プロファイルのデータセットを無効にする

プロファイルが有効になっているデータセットを更新用に設定するには、まず unifiedProfile タグと unifiedIdentity タグを無効化してから、それらを isUpsert タグとともに再度有効にします。これを実行するには、2 つの PATCH リクエストを使用します。1 回目のリクエストで無効にし、もう 1 回で再度有効にします。

API 形式

PATCH /dataSets/{DATASET_ID}

リクエスト

最初の PATCH リクエスト本文には、unifiedProfile への path および unifiedIdentity への path がが含まれ、タグを無効にするため、両方のパスで value を enabled:false に設定します。

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

応答

応答 PATCH リクエストが成功すると、HTTP ステータス 200（OK）と、更新されたデータセットの ID を含む配列が返されます。この ID は、PATCH リクエストで送信された ID と一致する必要があります。unifiedProfile タグと unifiedIdentity タグが無効になりました。

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

プロファイルでデータセットを有効にしてアップサートする enable-the-dataset

単一の PATCH リクエストを使用して、プロファイルと属性の更新に対して既存のデータセットを有効にできます。

API 形式

PATCH /dataSets/{DATASET_ID}

リクエスト

リクエスト本文には、unifiedProfile への path（value では enabled タグと isUpsert タグを含め、両方のタグを true にするよう設定）、および unifiedIdentity への path（value では enabled タグを含めて true にするよう設定）が含まれます。

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

応答

応答 PATCH リクエストが成功すると、HTTP ステータス 200（OK）と、更新されたデータセットの ID を含む配列が返されます。この ID は、PATCH リクエストで送信された ID と一致する必要があります。unifiedProfile タグと unifiedIdentity タグが有効になり、属性の更新用に設定されました。

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

次の手順

これで、プロファイルとアップサートが有効になっているデータセットをバッチ取得ワークフローで使用して、プロファイルデータを更新できるようになりました。 データを Adobe Experience Platform に取り込む方法の詳細については、まず データ取り込みの概要を参照してください。