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)：Platform が、カスタマーエクスペリエンスデータを整理する際に使用する、標準化されたフレームワーク。
- バッチ取り込み:Experience Platform が CSV や Parquet などのデータファイルからデータを取り込んで保存する方法。
- ストリーミング取得:Experience Platform がクライアントサイドおよびサーバーサイドのデバイスから、リアルタイムにデータを取得して保存する方法。
次の節では、Catalog Service API の呼び出しを正しくおこなうために知っておく必要がある、または手元に用意しておく必要がある追加情報を提供します。
API 呼び出し例の読み取り
ここでは、リクエストの形式を説明するために API 呼び出しの例を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーの値の収集
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization： Bearer
{ACCESS_TOKEN} - x-api-key：
{API_KEY} - x-gw-ims-org-id：
{ORG_ID}
Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。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 がデータ取り込みにどのように関係するかを示す詳細なワークフローについては、 データセットの作成に関するチュートリアルを参照してください。