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 呼び出しのドキュメントで使用されている規則については、Experience Platform トラブルシューテングガイドのサンプル API 呼び出しの読み方に関する節を参照してください。

必須ヘッダーの値の収集

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とデータ取り込みとの関わり方を示すワークフローについては、データセットの作成に関するチュートリアルを参照してください。

このページ