プロファイル書き出しジョブエンドポイント
Real-Time Customer Profile を使用すると、属性データと行動データの両方を含む複数のソースからデータを統合することで、個々の顧客の単一のビューを作成できます。 その後、さらに処理するために、プロファイルデータをデータセットに書き出すことができます。 例： Profile オーディエンスを作成することで、アクティベーション用にデータを書き出したり、レポート用にプロファイル属性を書き出したりできます。
このドキュメントでは、を使用してエクスポートジョブを作成および管理する手順を説明します プロファイル API.
エクスポートジョブの作成に加えて、にもアクセスできます。 Profile を使用したデータ /entities エンドポイント（「」とも呼ばれます）Profile Access」と入力します。 を参照してください。 エンティティエンドポイントガイド を参照してください。 アクセス方法の手順については、を参照してください Profile ui を使用したデータ。を参照してください。 ユーザーガイド.
はじめに
このガイドで使用する API エンドポイントは、 Real-Time Customer Profile API です。 先に進む前に、はじめる前にのガイドを参照し、関連ドキュメントへのリンク、このドキュメントのサンプル API 呼び出しを読み取るためのガイドおよび任意の Experience Platform API の呼び出しを成功させるのに必要なヘッダーに関する重要な情報を確認してください。
エクスポートジョブの作成
エクスポート Profile データを取得するには、まずデータの書き出し先となるデータセットを作成してから、新しい書き出しジョブを開始する必要があります。 これらの手順は両方とも、Experience PlatformAPI を使用して実行できます。前者は Catalog Service API を使用し、後者はリアルタイム顧客プロファイル API を使用します。 各手順を完了するための詳細な手順については、以下の節で説明しています。
ターゲットデータセットの作成
書き出し時 Profile データの場合、まずターゲットデータセットを作成する必要があります。 データセットを正しく設定して、エクスポートが正常に行われるようにすることが重要です。
重要な考慮事項の 1 つは、データセットのベースとなるスキーマ（以下の API サンプルリクエストの schemaRef.id）です。プロファイルデータを書き出すには、データセットはに基づいている必要があります XDM Individual Profile 結合スキーマ （https://ns.adobe.com/xdm/context/profile__union）に設定します。 結合スキーマは、同じクラスを共有するスキーマのフィールドを集約する、システム生成の読み取り専用スキーマです。 この場合、次のようになります XDM Individual Profile クラス。 和集合表示スキーマについて詳しくは、を参照してください。 スキーマ構成の基本ガイドの和集合の節.
このチュートリアルの手順では、を参照するデータセットの作成方法の概要を説明します XDM Individual Profile を使用した結合スキーマ Catalog API です。 を使用することもできます。 Platform 和集合スキーマを参照するデータセットを作成するためのユーザーインターフェイス。 UI の使用手順の概要については、を参照してください。 オーディエンスを書き出すための UI チュートリアル ただし、ここでも適用できます。 完了したら、このチュートリアルに戻り、新しいエクスポートジョブを開始する手順に進むことができます。
互換性のあるデータセットが既に存在し、その ID がわかっている場合は、新しいエクスポートジョブを開始する手順に直接進むことができます。
API 形式
POST /dataSets
リクエスト
次のリクエストは、新しいデータセットを作成し、ペイロードに設定パラメーターを提供します。
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": "Profile Data Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
nameschemaRef.id応答
応答に成功した場合、新しく作成されたデータセットの読み取り専用のシステム生成された一意の ID を含む配列が返されます。プロファイルデータを正常にエクスポートするには、適切に設定されたデータセット ID が必要です。
[
"@/datasets/5b020a27e7040801dedba61b"
]
エクスポートジョブの開始 initiate
和集合を保持するデータセットが用意できたら、に対してPOSTリクエストを行い、プロファイルデータをデータセットに保持する書き出しジョブを作成できます。 /export/jobs リアルタイム顧客プロファイル API のエンドポイントと、書き出すデータの詳細をリクエストの本文で指定します。
API 形式
POST /export/jobs
リクエスト
次のリクエストは、新しいエクスポートジョブを作成し、ペイロードに設定パラメーターを提供します。
curl -X POST https://platform.adobe.io/data/core/ups/export/jobs \
-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 '{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}'
fieldsmergePolicymergePolicy.idmergePolicy.versionadditionalFields.eventList（オプション） 次の 1 つ以上の設定を指定して、子または関連するオブジェクト用に書き出された時系列イベントフィールドを制御します。
eventList.fields：エクスポートするフィールドを制御します。eventList.filter：関連オブジェクトから取得される結果を制限する基準を指定します。エクスポートに必要な最小値（通常は日付）が基準として予期されます。eventList.filter.fromIngestTimestamp：時系列イベントを、指定されたタイムスタンプ以降に取り込まれたイベントにフィルターします。 これは、イベント時間自体ではなく、イベントの取得時間です。
destination（必須） エクスポートするデータの宛先情報：
destination.datasetId：（必須） データのエクスポート先のデータセットの ID。destination.segmentPerBatch：（オプション） 指定しない場合、ブール値はデフォルトでfalseになります。値falseすべてのセグメント定義 ID を単一のバッチ ID にエクスポートします。 値true1 つのセグメント定義 ID を 1 つのバッチ ID にエクスポートします。 値をtrueに設定すると、バッチエクスポートのパフォーマンスに影響を与える場合があることに注意してください。
schema.name応答
成功した応答では、リクエストで指定したプロファイルデータが含まれるデータセットが返されます。
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 24115,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"version": 1
},
"status": "NEW",
"requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
"computeGatewayJobId": {},
"metrics": {
"totalTime": {
"startTimeInMs": 1559674261657
}
},
"destination": {
"dataSetId": "5cf6bcf79ecc7c14530fe436",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
すべてのエクスポートジョブのリスト
に対してGETリクエストを実行することで、特定の組織のすべての書き出しジョブのリストを返すことができます export/jobs エンドポイント。 リクエストは、以下に示すように、クエリパラメーター limit および offset もサポートします。
API 形式
GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
startstart=4limitlimit=10pagepage=2sortasc ）または降順（ desc ）の順序です。 結果の複数ページを返す場合、並べ替えパラメーターは機能しません。例：sort=updateTime:ascリクエスト
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs/ \
-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}'
応答
応答には次が含まれます records 組織で作成された書き出しジョブを含むオブジェクト。
{
"records": [
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 726,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"status": "SUCCEEDED",
"requestId": "d995479c-8a08-4240-903b-af469c67be1f",
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
"pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1538615973895,
"endTimeInMs": 1538616233239,
"totalTimeInMs": 259344
},
"profileExportTime": {
"startTimeInMs": 1538616067445,
"endTimeInMs": 1538616139576,
"totalTimeInMs": 72131
},
"aCPDatasetWriteTime": {
"startTimeInMs": 1538616195172,
"endTimeInMs": 1538616195715,
"totalTimeInMs": 543
}
},
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1538616233239,
"imsOrgId": "{ORG_ID}",
"creationTime": 1538615973895
},
{
"profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
"errors": [
{
"code": "0090000009",
"msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
"callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
},
{
"code": "unknown",
"msg": "Job aborted.",
"callStack": "org.apache.spark.SparkException: Job aborted."
}
],
"jobType": "BATCH",
"filter": {
"segments": [
{
"segmentId": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
}
]
},
"id": 722,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
"version": 1
},
"status": "FAILED",
"requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
"computeGatewayJobId": {
"exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1538573416687,
"endTimeInMs": 1538573922551,
"totalTimeInMs": 505864
},
"profileExportTime": {
"startTimeInMs": 1538573872211,
"endTimeInMs": 1538573918809,
"totalTimeInMs": 46598
}
},
"destination": {
"datasetId": "5bb4c46757920712f924a3eb",
"batchId": ""
},
"updateTime": 1538573922551,
"imsOrgId": "{ORG_ID}",
"creationTime": 1538573416687
}
],
"page": {
"sortField": "createdTime",
"sort": "desc",
"pageOffset": "1538573416687_722",
"pageSize": 2
},
"link": {
"next": "/export/jobs/?limit=2&offset=1538573416687_722"
}
}
エクスポートの進行状況の監視
特定のエクスポートジョブの詳細を表示したり、処理中のステータスを監視したりするには、/export/jobs エンドポイントに対して GET リクエストを実行し、エクスポートジョブの id をパスを含めます。status フィールドによって値「SUCCEEDED」が返されると、エクスポートジョブが完了します。
API 形式
GET /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}id。リクエスト
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs/24115 \
-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}'
応答
{
"profileInstanceId": "ups",
"jobType": "BATCH",
"id": 24115,
"schema": {
"name": "_xdm.context.profile"
},
"mergePolicy": {
"id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
"version": 1
},
"status": "SUCCEEDED",
"requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
"computeGatewayJobId": {
"exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
"pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
},
"metrics": {
"totalTime": {
"startTimeInMs": 1547053539564,
"endTimeInMs": 1547054743929,
"totalTimeInMs": 1204365
},
"profileExportTime": {
"startTimeInMs": 1547053667591,
"endTimeInMs": 1547053778195,
"totalTimeInMs": 110604
},
"aCPDatasetWriteTime": {
"startTimeInMs": 1547054660416,
"endTimeInMs": 1547054698918,
"totalTimeInMs": 38502
}
},
"destination": {
"dataSetId": "5cf6bcf79ecc7c14530fe436",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"updateTime": 1559674261868,
"imsOrgId": "{ORG_ID}",
"creationTime": 1559674261657
}
batchIdエクスポートジョブのキャンセル
Experience Platform では、既存のエクスポートジョブをキャンセルできます。この機能は、エクスポートジョブが完了しなかったか、処理段階で停止した場合など、様々な理由で役立つ場合があります。エクスポートジョブをキャンセルするには、/export/jobs エンドポイントに対して DELETE リクエストを実行し、キャンセルするエクスポートジョブの id をリクエストパスに含めます。
API 形式
DELETE /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}id。リクエスト
curl -X POST https://platform.adobe.io/data/core/ups/export/jobs/726 \
-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}'
応答
削除リクエストが成功すると、HTTP ステータス 204（コンテンツなし）と空の応答本文が返され、キャンセル操作が成功したことを示します。
次の手順
エクスポートが正常に完了すると、データは Experience Platform のデータレイク内で使用できます。その後、エクスポートに関連付けられた batchId を使用して、データアクセス API でデータにアクセスできます。エクスポートのサイズに応じて、データがチャンクに格納され、バッチが複数のファイルで構成される場合があります。
データアクセス API を使用してバッチファイルにアクセスしてダウンロードする手順については、データアクセスのチュートリアルを参照してください。
また、Adobe Experience Platform クエリサービスを使用して、正常に書き出されたリアルタイム顧客プロファイルデータにアクセスすることもできます。 クエリサービスでは、UI または RESTful API を使用して、クエリの書き込みと検証を行い、データレイク内のデータに対してクエリを実行することができます。
オーディエンスデータに対してクエリを実行する方法ついて詳しくは、クエリサービスのドキュメントを参照してください。
付録
次の節では、Profile API の書き出しジョブに関する追加情報を示します。
その他のエクスポートペイロードの例
API 呼び出しの例を、の節で示します。 エクスポートジョブの開始 プロファイル（レコード）とイベント（時系列）の両方のデータを含むジョブを作成します。 この節では、エクスポートするデータ型を 1 つのみに制限する、追加のリクエストペイロードの例を示します。
次のペイロードは、プロファイルデータのみを含み（イベントを含まない）、書き出しジョブを作成します。
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
イベントデータのみを含む（プロファイル属性を含まない）書き出しジョブを作成するには、ペイロードは次のようになります。
{
"fields": "identityMap",
"mergePolicy": {
"id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
"version": 1
},
"additionalFields": {
"eventList": {
"fields": "environment.browserDetails.name,environment.browserDetails.version",
"filter": {
"fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
}
}
},
"destination": {
"datasetId": "5b020a27e7040801dedba61b",
"segmentPerBatch": false
},
"schema": {
"name": "_xdm.context.profile"
}
}
オーディエンスの書き出し
代わりに、エクスポートジョブエンドポイントを使用して、オーディエンスをエクスポートすることもできます。 Profile データ。 のガイドを参照してください segmentation API でのジョブの書き出し を参照してください。