Show Menu
トピック×

Adobe Experience Platform へのレコードデータのストリーミング

This tutorial will help you begin using streaming ingestion APIs, part of the Adobe Experience Platform Data Ingestion Service APIs.

はじめに

このチュートリアルでは、Adobe Experience Platform の各種サービスに関する実用的な知識が必要です。このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。
  • Experience Data Model (XDM) :エクスペリエンスデータを Platform 編成するための標準化されたフレームワーク。
  • リアルタイム顧客プロファイル :複数のソースからの集計データに基づいて、リアルタイムで統合された顧客プロファイルを提供します。
  • スキーマレジストリ開発ガイド :APIの使用可能な各エンドポイントと、それらのエンドポイントへの呼び出し方法をカバーする包括的なガイドです。 Schema Registry これには、このチュートリアル全体の呼び出しで表示される {TENANT_ID} の理解と、取得用のデータセットの作成に使用されるスキーマの作成方法の理解が含まれます。
また、このチュートリアルでは、既にストリーミング接続を作成している必要があります。ストリーミング接続の作成について詳しくは、『 ストリーミング接続作成のチュートリアル 』を参照してください。
以下の節では、ストリーミング取得 API の呼び出しを正常におこなうために知っておく必要がある追加情報を示します。

API 呼び出し例の読み取り

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

必須ヘッダーの値の収集

In order to make calls to Platform APIs, you must first complete the authentication tutorial . Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:
  • x-sandbox-name: {SANDBOX_NAME}
For more information on sandboxes in Platform, see the sandbox overview documentation .
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。
  • Content-Type: application/json

Compose a schema based off of the XDM Individual Profile class

To create a dataset, you will first need to create a new schema that implements the XDM Individual Profile class. スキーマの作成方法について詳しくは、『 スキーマレジストリ API 開発者ガイド 』を参照してください。
API 形式
POST /schemaregistry/tenant/schemas

リクエスト
curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "type": "object",
    "title": "Sample schema",
    "description": "Sample description",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
        }
    ],
    "meta:immutableTags": [
        "union"
    ]
  }'

プロパティ
説明
title
スキーマ名。この名前は一意である必要があります。
description
作成するスキーマのわかりやすい説明。
meta:immutableTags
In this example, the union tag is used to persist your data into Real-time Customer Profile .
応答  
正常な応答は、HTTP ステータス 201 と、新しく作成されたスキーマの詳細を返します。
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "type": "object",
    "title": "Sample schema",
    "description": "Sample description",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
        }
    ],
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/cpmtext/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-work-details"
    ],
    "meta:immutableTags": [
        "union"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createDate": 1551376506996,
        "repo:lastModifiedDate": 1551376506996,
        "xdm:createdClientId": "{CLIENT_ID}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

プロパティ
説明
{TENANT_ID}
この ID は、作成するリソースの名前空間が適切に設定され、IMS 組織内に含まれるようにするために使用されます。テナント ID の詳細については、『 スキーマレジストリガイド 』を参照してください。
データセットを作成する際には、 $id 属性と version 属性の両方が使用されるので、注意してください。

スキーマのプライマリ ID 記述子の設定

次に、仕事用電子メールアドレス属性をプライマリ識別子として使用して、上で作成した識別子に ID 記述子 を追加します。これをおこなうと、次の 2 つの変更が行われます。
  1. 仕事用電子メールアドレスは必須フィールドになります。つまり、このフィールドなしで送信されたメッセージは検証に失敗し、取得されません。
  2. Real-time Customer Profile は、勤務先の電子メールアドレスを識別子として使用して、その個人に関する詳細情報を結合します。

リクエスト

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "@type":"xdm:descriptorIdentity",
    "xdm:sourceProperty":"/workEmail/address",
    "xdm:property":"xdm:code",
    "xdm:isPrimary":true,
    "xdm:namespace":"Email",
    "xdm:sourceSchema":"{SCHEMA_REF_ID}",
    "xdm:sourceVersion":1
}

プロパティ
説明
{SCHEMA_REF_ID}
以前にスキーマを構成したときに受け取った $id 。次のようになります。 "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}"
​ ​ ID 名前空間コード
コードが有効であることを確認してください。上記の例では、標準の ID 名前空間である「email」を使用しています。その他の一般的に使用される標準 ID 名前空間は、 ID サービスの FAQ に記載されています。
カスタム名前空間を作成する場合は、 ID 名前空間の概要 で説明している手順に従います。
応答  
成功時の応答は、HTTP ステータス 201 と共に、スキーマ用に新しく作成されたプライマリ ID 記述子に関する情報を返します。
{
    "xdm:property": "xdm:code",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "xdm:namespace": "Email",
    "@type": "xdm:descriptorIdentity",
    "xdm:sourceVersion": 1,
    "xdm:isPrimary": true,
    "xdm:sourceProperty": "/workEmail/address",
    "@id": "17aaebfa382ce8fc0a40d3e43870b6470aab894e1c368d16",
    "meta:containerId": "tenant",
    "version": "1",
    "imsOrg": "{IMS_ORG}"
}

レコードデータのデータセットの作成

スキーマを作成したら、レコードデータを取り込むためのデータセットを作成する必要があります。
このデータセットは、 Real-time Customer Profile およびで有効になり Identity Service ​ます。
API 形式
POST /catalog/dataSets

リクエスト
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d ' {
    "name": "Dataset name",
    "description": "Dataset description",
    "schemaRef": {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID},
        "contentType": "application/vnd.adobe.xed-full+json;version=1.0"
    },
    "tags": {
        "unifiedIdentity": ["enabled:true"],
        "unifiedProfile": ["enabled:true"]
    }
}'

応答  
成功時の応答は、HTTP ステータス 201 と共に、新しく作成されたデータセットの ID を @/dataSets/{DATASET_ID} の形式で含む配列を返します。
[
    "@/dataSets/5e30d7986c0cc218a85cee65
]

ストリーミング接続へのレコードデータの取り込み

With the dataset and streaming connection in place, you can ingest XDM-formatted JSON records to ingest record data into Platform.
API 形式
POST /collection/{CONNECTION_ID}?synchronousValidation=true

パラメーター
説明
{CONNECTION_ID}
作成済みのストリーミング接続の id 値です。
synchronousValidation
開発用のクエリパラメーター(オプション)。 true に設定した場合、リクエストが正常に送信されたかどうかを確認するために、即座のフィードバックに使用できます。デフォルトでは、この値は false に設定されています。
リクエスト
以下の API 呼び出しでは、認証ヘッダーは​ 必要ありません
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?synchronousValidation=true \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "datasetId": "{DATASET_ID}"
    },
    "body": {
        "xdmMeta": {
            "schemaRef": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
                "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
            }
        },
        "xdmEntity": {
            "person": {
                "name": {
                    "firstName": "Jane",
                    "middleName": "F",
                    "lastName": "Doe"
                },
                "birthDate": "1969-03-14",
                "gender": "female"
            },
            "workEmail": {
                "primary": true,
                "address": "janedoe@example.com",
                "type": "work",
                "status": "active"
            }
        }
    }
}'

応答  
A successful response returns HTTP status 200 with details of the newly streamed Profile.
{
    "inletId": "{CONNECTION_ID}",
    "xactionId": "1584479347507:2153:240",
    "receivedTimeMs": 1584479347507,
    "synchronousValidation": {
        "status": "pass"
    }
}

プロパティ
説明
{CONNECTION_ID}
以前に作成したストリーミング接続の ID。
xactionId
先ほど送信したレコードに対してサーバーサイドで生成された一意の識別子。この IDは、様々なシステムやデバッグを通じて、アドビがこのレコードのライフサイクルを追跡するのに役立ちます。
receivedTimeMs
リクエストが受信された時刻を示すタイムスタンプ(ミリ秒単位のエポックタイム)。
synchronousValidation.status
synchronousValidation=true クエリパラメーターが追加されたので、この値が表示されます。検証が成功した場合、ステータスは pass になります。

新しく取り込んだレコードデータの取得

To validate the previously ingested records, you can use the Profile Access API to retrieve the record data.
マージポリシーIDが定義されておらず、またはが定義されていない場合、 schema.name はす relatedSchema.name べての _xdm.context.profile 関連IDを取得し Profile Access ます。
API 形式
GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email

パラメーター
説明
schema.name
必須. 。アクセスするスキーマの名前です。
entityId
エンティティの ID です。指定する場合は、エンティティの名前空間も指定します。
entityIdNS
取得しようとしている ID の名前空間。
リクエスト
既に取り込んだレコードデータは、次の GET リクエストで確認できます。
curl -X GET 'https://platform.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email'\
  -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}'

応答  
成功時の応答は、HTTP ステータス 200 と共に、要求されたエンティティの詳細を返します。これは以前に正常に取り込まれた記録と同じであることがわかります。
{
    "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA": {
        "entityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
        "mergePolicy": {
            "id": "e161dae9-52f0-4c7f-b264-dc43dd903d56"
        },
        "sources": [
            "5e30d7986c0cc218a85cee65"
        ],
        "tags": [
            "1580346827274:2478:215"
        ],
        "identityGraph": [
            "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA"
        ],
        "entity": {
            "person": {
                "name": {
                    "lastName": "Doe",
                    "middleName": "F",
                    "firstName": "Jane"
                },
                "gender": "female",
                "birthDate": "1969-03-14"
            },
            "workEmail": {
                "type": "work",
                "address": "janedoe@example.com",
                "status": "active",
                "primary": true
            },
            "identityMap": {
                "email": [
                    {
                        "id": "janedoe@example.com"
                    }
                ]
            }
        },
        "lastModifiedAt": "2020-01-30T01:13:59Z"
    }
}

次の手順

By reading this document, you now understand how to ingest record data into Platform using streaming connections. 異なる値でさらに呼び出しを実行し、更新された値を取得してみてください。Additionally, you can start monitoring your ingested data through Platform UI. 詳しくは、『 データ取得監視ガイド 』を参照してください。
一般的なストリーミング取得の詳細については、『 ストリーミング取得の概要 』を参照してください。