Catalog Service API ガイド
Catalog Service は、Adobe Experience Platform 内のデータの場所と系列の記録システムです。 Catalogは、メタデータ ストアまたは「カタログ」として機能し、Experience Platform内でデータに関する情報を検索できます。データ自体にアクセスする必要はありません。 詳しくは、Catalog 概要を参照してください。
このデベロッパーガイドでは、Catalog API を使い始めるのに役立つ手順を説明します。 次に、このガイドでは、Catalogを使用してキー操作を実行するためのサンプル API呼び出しを提供します。
前提条件
Catalogは、Experience Platform内の複数の種類のリソースと操作のメタデータを追跡します。 この開発者ガイドでは、これらのリソースの作成と管理に関する様々なExperience Platform サービスについて理解する必要があります。
- Experience Data Model (XDM)：Experience Platform が、カスタマーエクスペリエンスデータを整理する際に使用する、標準化されたフレームワーク。
- バッチ取り込み: Experience PlatformがCSVやParquetなどのデータファイルからデータを取り込み、保存する方法。
- ストリーミング取得: Experience Platformがクライアントサイドおよびサーバーサイドのデバイスからデータをリアルタイムで取り込み、保存する方法。
次の節では、Catalog Service APIの呼び出しを正常に行うために知っておく必要がある、または手元にある必要がある追加情報を示します。
API 呼び出し例の読み取り
ここでは、リクエストの形式を説明するために API 呼び出しの例を示します。 これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。 また、API レスポンスで返されるサンプル JSON も示されています。 ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーの値の収集
Experience Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。 次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization: Bearer
{ACCESS_TOKEN} - x-api-key：
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。 Experience Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
- x-sandbox-name：
{SANDBOX_NAME}
ペイロード（POST、PUT、PATCH）を含んだすべてのリクエストには、以下の追加ヘッダーが必要です。
- Content-Type：application/json
Catalog API呼び出しのベストプラクティス
Catalog APIに対してGET リクエストを実行する場合、必要なオブジェクトとプロパティのみを返すために、リクエストにクエリパラメーターを含めることがベストプラクティスです。 フィルターを適用しないリクエストの応答ペイロードのサイズは 3 GB に達っすることがあり、全体的なパフォーマンスが低下する可能性があります。
特定のオブジェクトを表示するには、リクエストパスに ID を含めるか、または properties や limit などのクエリーパラメーターを使用して応答をフィルターします。 フィルターは、ヘッダーおよびクエリーパラメーターとして渡すことができ、クエリーパラメーターとして渡されたフィルターが優先されます。 詳しくは、カタログデータのフィルターに関するドキュメントを参照してください。
一部のクエリではAPIに大きな負荷がかかる可能性があるため、ベストプラクティスをさらにサポートするために、Catalog クエリにグローバル制限が実装されました。
次の手順
このドキュメントでは、Catalog API を呼び出すために必要な前提条件に関する知識を説明しました。 これで、この開発者ガイドに記載されているサンプル呼び出しに進んで、その手順に従うことができます。
このガイドの例のほとんどは/dataSets エンドポイントを使用していますが、原則はCatalog内の他のエンドポイント（/batchesなど）に適用できます。 各エンドポイントで使用できるすべての呼び出しと操作の完全なリストについては、『カタログサービス API リファレンス』を参照してください。
Catalog APIがデータ取り込みにどのように関連しているかを示すステップバイステップのワークフローについては、 データセットの作成に関するチュートリアルを参照してください。