Show Menu
トピック×

API を使用したデータセットの作成

このドキュメントでは、Adobe Experience Platform API を使用してデータセットを作成し、ファイルを使用してデータセットを設定する一般的な手順を説明します。

はじめに

このガイドでは、Adobe Experience Platform の次のコンポーネントに関する作業を理解している必要があります。
  • バッチインジェスト : Experience Platform データをバッチファイルとして取り込むことができます。
  • Experience Data Model (XDM) System :顧客体験データを Experience Platform 整理する際に使用される標準化されたフレームワーク。
  • サンドボックス : Experience Platform は、1つの Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスを提供します。
The following sections provide additional information that you will need to know in order to successfully make calls to the Platform APIs.

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

チュートリアル

データセットを作成するには、まずスキーマを定義する必要があります。スキーマは、データを表すのに役立つ一連のルールです。スキーマは、データの構造を説明するだけでなく、システム間を移動するデータを検証するために適用および使用できる制約と期待を提供します。
これらの標準的な定義により、タッチチャネルに関係なくデータを一貫して解釈でき、アプリケーション間での翻訳の必要性を排除できます。スキーマの構成について詳しくは、 基本的なスキーマ構成のガイド を参照してください。

データセットスキーマの検索

このチュートリアルは、 スキーマレジストリ API チュートリアル が終わったところから始まり、チュートリアルの中で作成したロイヤルティメンバースキーマを利用します。
If you have not completed the Schema Registry tutorial, please start there and continue with this dataset tutorial only once you have composed the necessary schema.
The following call can be used to view the Loyalty Members schema you created during the Schema Registry API tutorial:
API 形式
GET /tenant/schemas/{schema meta:altId or URL encoded $id URI}

リクエスト
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9 \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \
  -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}'

応答  
応答オブジェクトの形式は、リクエストで送信される Accept ヘッダーによって異なります。この応答の個々のプロパティは、スペースを節約するために最小化にされました。
{
    "type": "object",
    "title": "Loyalty Members",
    "description": "Information for all members of the loyalty program",
    "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/context/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-personal-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/bb118e507bb848fd85df68fedea70c62"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:immutableTags": [
        "union"
    ],
    "meta:altId": "_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9",
    "meta:xdmType": "object",
    "properties": {
        "repositoryCreatedBy": {},
        "repositoryLastModifiedBy": {},
        "createdByBatchID": {},
        "modifiedByBatchID": {},
        "_repo": {},
        "identityMap": {},
        "_id": {},
        "timeSeriesEvents": {},
        "person": {},
        "homeAddress": {},
        "personalEmail": {},
        "homePhone": {},
        "mobilePhone": {},
        "faxPhone": {},
        "_{TENANT_ID}": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "loyalty": {
                    "title": "Loyalty",
                    "description": "Loyalty Info",
                    "type": "object",
                    "meta:xdmType": "object",
                    "meta:referencedFrom": "https://ns.adobe.com/{TENANT_ID}/datatypes/49b594dabe6bec545c8a6d1a0991a4dd",
                    "properties": {
                        "loyaltyId": {
                            "title": "Loyalty Identifier",
                            "type": "string",
                            "description": "Loyalty Identifier.",
                            "meta:xdmType": "string"
                        },
                        "loyaltyLevel": {
                            "title": "Loyalty Level",
                            "type": "string",
                            "meta:xdmType": "string"
                        },
                        "loyaltyPoints": {
                            "title": "Loyalty Points",
                            "type": "integer",
                            "description": "Loyalty points total.",
                            "meta:xdmType": "int"
                        },
                        "memberSince": {
                            "title": "Member Since",
                            "type": "string",
                            "format": "date-time",
                            "description": "Date the member joined the Loyalty Program.",
                            "meta:xdmType": "date-time"
                        }
                    }
                }
            }
        }
    },
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
    "version": "1.4",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1551836845496,
        "repo:lastModifiedDate": 1551843052271,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

データセットの作成

「ロイヤルティメンバー」スキーマが完成したら、そのスキーマを参照するデータセットを作成できます。
API 形式
POST /dataSets

リクエスト
curl -X POST \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
  -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":"LoyaltyMembersDataset",
    "schemaRef": {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/719c4e19184402c27595e65b931a142b",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    },
    "fileDescription": {
        "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    }
}'

このチュートリアルの全例では、 parquet ファイル形式を使用します。JSON ファイル形式の使用例については、 バッチ取得開発ガイド を参照してください。
応答  
成功した応答は、HTTP Status 201(作成済み)と、新しく作成されたデータセットの ID を "@/datasets/{DATASET_ID}" 形式で含む配列で構成される応答オブジェクトを返します。データセット ID は、API 呼び出しでデータセットを参照するために使用される、読み取り専用のシステム生成文字列です。
[
    "@/dataSets/5c8c3c555033b814b69f947f"
]

バッチの作成

データセットにデータを追加する前に、データセットにリンクするバッチを作成する必要があります。その後、バッチがアップロードに使用されます。
API 形式
POST /batches

リクエスト
リクエスト本文には、前の手順で生成された {DATASET_ID} の値を示す「datasetId」フィールドが含まれています。
curl -X POST 'https://platform.adobe.io/data/foundation/import/batches' \
  -H 'accept: application/json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
        "datasetId":"5c8c3c555033b814b69f947f"
      }'

応答  
成功した応答は、HTTP ステータス 201(作成済み)と、新しく作成されたバッチの詳細を含む応答オブジェクトを返します。これには、読み取り専用のシステム生成文字列である id が含まれます。
{
    "id": "5d01230fc78a4e4f8c0c6b387b4b8d1c",
    "imsOrg": "{IMS_ORG}",
    "updated": 1552694873602,
    "status": "loading",
    "created": 1552694873602,
    "relatedObjects": [
        {
            "type": "dataSet",
            "id": "5c8c3c555033b814b69f947f"
        }
    ],
    "version": "1.0.0",
    "tags": {
        "acp_producer": [
            "{CREATED_CLIENT}"
        ],
        "acp_stagePath": [
            "{CREATED_CLIENT}/stage/5d01230fc78a4e4f8c0c6b387b4b8d1c"
        ],
        "use_plan_b_batch_status": [
            "false"
        ]
    },
    "createdUser": "{CREATED_BY}",
    "updatedUser": "{CREATED_BY}",
    "externalId": "5d01230fc78a4e4f8c0c6b387b4b8d1c",
    "createdClient": "{CREATED_CLIENT}",
    "inputFormat": {
        "format": "parquet"
    }
}

ファイルのバッチへのアップロード

アップロード用の新しいバッチが正常に作成されたら、特定のデータセットにファイルをアップロードできるようになりました。データセットを定義する際に、ファイル形式を parquet として指定したことを忘れないでください。したがって、アップロードするファイルはその形式である必要があります。
サポートされるデータアップロードファイルの最大サイズは 512 MB です。データファイルのサイズがこれより大きい場合は、512 MB 以下のチャンクに分割し、一度に 1 つずつアップロードする必要があります。同じバッチ ID を使用して、各ファイルに対してこの手順を繰り返すことで、各ファイルを同じバッチにアップロードできます。ファイルをバッチの一部としてアップロードできる場合、数に制限はありません。
API 形式
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

パラメーター
説明
{BATCH_ID}
アップロード先のバッチの id
{DATASET_ID}
バッチを保持するデータセットの id
{FILE_NAME}
アップロードするファイルの名前。
リクエスト
curl -X PUT 'https://platform.adobe.io/data/foundation/import/batches/5d01230fc78a4e4f8c0c6b387b4b8d1c/datasets/5c8c3c555033b814b69f947f/files/loyaltyData.parquet' \
  -H 'content-type: application/octet-stream' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMG_ORG}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '@{FILE_PATH_AND_NAME}.parquet'

応答  
正常にアップロードされたファイルは、空の応答本文と HTTP ステータス 200(OK)を返します。

シグナルバッチ完了

すべてのデータファイルをバッチにアップロードした後、バッチに完了を知らせることができます。Signaling completion causes the service to create Catalog DataSetFile entries for the uploaded files and associate them with the batch generated previously. The Catalog batch is marked successful, which triggers any downstream flows that can then work on the now available data.
API 形式
POST /batches/{BATCH_ID}?action=COMPLETE

パラメーター
説明
{BATCH_ID}
完了としてマークするバッチの id
リクエスト
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/5d01230fc78a4e4f8c0c6b387b4b8d1c?action=COMPLETE" \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMG_ORG}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

応答  
正常に完了したバッチは、空の応答本文と HTTP ステータス 200(OK)を返します。

取得の監視

データのサイズに応じて、バッチ取得には様々な時間がかかります。バッチの ID を含む batch リクエストパラメーターを GET /batches リクエストに追加することで、バッチのステータスを監視できます。API は、データセットをポーリングし、バッチの取得から、応答内の status が完了(「成功」または「失敗」)を示すまでの状態を調べます。
API 形式
GET /batches?batch={BATCH_ID}

パラメーター
説明
{BATCH_ID}
監視するバッチの id
リクエスト
curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/batches?batch=5d01230fc78a4e4f8c0c6b387b4b8d1c' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMG_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'

応答  
正の応答は、 success の値を含む status 属性を持つオブジェクトを返しま す。
{
    "5b7129a879323401ef2a6486": {
        "imsOrg": "{IMS_ORG}",
        "created": 1534142888068,
        "createdClient": "{CREATED_CLIENT}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "updated": 1534142955152,
        "replay": {},
        "status": "success",
        "errors": [],
        "version": "1.0.3",
        "availableDates": {},
        "relatedObjects": [
            {
                "type": "batch",
                "id": "29285e08378f4a41827e7e70fb7cb8f0"
            }
        ],
        "metrics": {
            "startTime": 1534142943819,
            "endTime": 1534142951760,
            "recordsRead": 108,
            "recordsWritten": 108
        }
    }
}

負の応答は、 "status" 属性に "failed" の値を持つオブジェクトを返し、次の関連するエラーメッセージが含まれます。
{
    "5b96ce65badcf701e51f075d": {
        "imsOrg": "{IMS_ORG}",
        "status": "failed",
        "relatedObjects": [
            {
                "type": "batch",
                "id": "29285e08378f4a41827e7e70fb7cb8f0"
            }
        ],
        "replay": {},
        "availableDates": {},
        "metrics": {
            "startTime": 1536610322329,
            "endTime": 1536610438083,
            "recordsRead": 4004,
            "recordsWritten": 4004,
            "failureReason": "Job aborted due to stage failure: Task 0 in stage 1.0 failed 4 times,:"
        },
        "errors": [
            {
                "code": "0070000017",
                "description": "Unknown error occurred."
            },
            {
                "code": "unknown",
                "description": "Job aborted."
            }
        ],
        "created": 1536609893629,
        "createdClient": "{CREATED_CLIENT}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "updated": 1536610442814,
        "version": "1.0.5"
    }
}

推奨されるポーリング間隔は 2 分です。

データセットからのデータの読み取り

バッチ ID を使用すると、データアクセス API を使用して、バッチにアップロードされたすべてのファイルを読み戻し、確認できます。応答は、ファイル ID のリストを含む配列を返し、それぞれがバッチ内のファイルを参照します。
また、データアクセス API を使用して、名前、サイズ(バイト)、ファイルまたはフォルダーをダウンロードするためのリンクを返すこともできます。
データアクセス API を使用する詳細な手順は、『 データアクセス開発ガイド 』を参照してください。

データセットスキーマの更新

フィールドを追加し、作成したデータセットに追加のデータを取得することができます。これをおこなうには、まず、新しいデータを定義する追加のスキーマを追加して、データを更新する必要があります。これは、PATCH 操作や PUT 操作を使用して、既存のスキーマを更新することができます。
スキーマの更新について詳しくは、『 スキーマレジストリ API 開発者ガイド を参照してください』。
スキーマを更新したら、このチュートリアルの手順に従って、変更後のスキーマに合う新しいデータを取得します。
スキーマの進化は純粋に付加的なものであることを覚えておくことが重要です。つまり、スキーマをレジストリに保存してデータの取得に使用すると、スキーマに重大な変更を加えることはできません。Adobe Experience Platform で使用するスキーマを構成するためのベストプラクティスについて詳しくは、 スキーマ構成の基本に関するガイド を参照してください。