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 や Parket などのデータファイルからデータを取得して保存する方法。
  • ストリーミング取り込み:クライ 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: {IMS_ORG}

Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。

  • x-sandbox-name: {SANDBOX_NAME}
メモ

Platform のサンドボックスについて詳しくは、サンドボックスの概要に関するドキュメントを参照してください。

ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。

  • Content-Type: application/json

Catalog API 呼び出しのベストプラクティス

Catalog API に対してGETリクエストを実行する場合、必要なオブジェクトとプロパティのみを返すように、リクエストにクエリパラメーターを含めることをお勧めします。 フィルターを適用しないリクエストの応答ペイロードのサイズは 3 GB に達っすることがあり、全体的なパフォーマンスが低下する可能性があります。

特定のオブジェクトを表示するには、リクエストパスに ID を含めるか、または propertieslimit などのクエリーパラメーターを使用して応答をフィルターします。フィルターは、ヘッダーおよびクエリーパラメーターとして渡すことができ、クエリーパラメーターとして渡されたフィルターが優先されます。詳しくは、カタログデータのフィルターに関するドキュメントを参照してください。

一部のクエリは API に大きな負荷をかける可能性があるので、ベストプラクティスをさらにサポートするために、Catalog クエリにグローバル制限が実装されました。

次の手順

このドキュメントでは、Catalog API を呼び出すために必要な前提条件に関する知識を説明しました。 これで、この開発者ガイドに記載されているサンプル呼び出しに進んで、その手順に従うことができます。

このガイドの例のほとんどは /dataSets エンドポイントを使用していますが、原則は Catalog 内の他のエンドポイント(/batches/accounts など)に適用できます。 各エンドポイントで使用できるすべての呼び出しと操作の完全なリストについては、『カタログサービス API リファレンス』を参照してください。

Catalog API とデータ取得との関わり方を示すワークフローについては、 データセットの作成 に関するチュートリアルを参照してください。

このページ