このドキュメントでは、Adobe Experience Platformに関するよくある質問と、Experience Platform APIで発生する可能性のある一般的なエラーの高レベルのトラブルシューティングガイドに回答します。 個々のPlatformサービスのトラブルシューティングガイドについては、下のサービストラブルシューティングディレクトリを参照してください。
次に、Adobe Experience Platform に関するよくある質問に対する回答をリストします。
Experience Platform オファーは、HTTP要求を使用してリ Platform ソースにアクセスする複数のRESTful APIを提供します。これらのサービス API は、それぞれ複数のエンドポイントを公開し、リスト(GET)、ルックアップ(GET)、編集(PUT または PATCH)および削除(DELETE)リソースに対する操作を実行できます。各サービスで使用できる特定のエンドポイントと操作について詳しくは、Adobe I/O の API リファレンスドキュメントを参照してください。
リクエストの形式は、使用するPlatform APIによって異なります。 API呼び出しの構造を学ぶ最善の方法は、使用している特定のPlatformサービスのドキュメントに記載されている例に従うことです。
Experience Platformのドキュメントには、2つの異なる方法でAPI呼び出しの例が示されています。 まず、呼び出しは API 形式で表されます。これは、操作(GET、POST、PUT、PATCH、DELETE など)と使用中のエンドポイント(例えば、/global/classes
)のみを示すテンプレート表現です。また、テンプレートには、GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}
などの呼び出しの作成方法を示すために、変数の位置を示すものもあります。
その後、呼び出しは、リクエスト内の cURL コマンドとして表示されます。これには、API とのやり取りに必要なヘッダーと完全な「ベースパス」が含まれます。ベースパスは、すべてのエンドポイントの前に追加する必要があります。例えば、前述の /global/classes
エンドポイントは https://platform.adobe.io/data/foundation/schemaregistry/global/classes
になります。API 形式とリクエストパターンはドキュメントを通して示されています。独自で Platform API を呼び出す場合は、例のリクエストに示す完全なパスを使用する必要があります。
以下は、ドキュメントで使用される形式を示す API リクエストの例です。
API 形式
API 形式は、操作(GET)と使用されているエンドポイントを示します。変数は中括弧で示されます(この場合は {CONTAINER_ID}
)。
GET /{CONTAINER_ID}/classes
リクエスト
この例のリクエストでは、API 形式の変数には、リクエストパス内の実際の値が与えられます。必要なすべてのヘッダーと、サンプルのヘッダー値、または機密情報(セキュリティトークンやアクセス ID など)を含めるための変数が表示されます。
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-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}'
応答
この応答は、送信されたリクエストに基づいて、API の呼び出しが成功した後に何を受け取るかを示します。場合によっては、応答がスペースを節約するために切り捨てられいるため、サンプルに表示されている情報に加えて他の情報が表示されることがあります。
{
"results": [
{
"title": "XDM ExperienceEvent",
"$id": "https://ns.adobe.com/xdm/context/experienceevent",
"meta:altId": "_xdm.context.experienceevent",
"version": "1"
},
{
"title": "XDM Individual Profile",
"$id": "https://ns.adobe.com/xdm/context/profile",
"meta:altId": "_xdm.context.profile",
"version": "1"
}
],
"_links": {}
}
必要なヘッダーやリクエスト本文を含む、Platform API の特定のエンドポイントについて詳しくは、API リファレンスのドキュメントを参照してください。
IMS 組織は、顧客のアドビ代表です。ライセンスを取得したアドビのソリューションは、この顧客組織に統合されます。IMS組織にExperience Platformへの権利が付与されると、開発者にアクセスを割り当てることができます。 IMS 組織 ID(x-gw-ims-org-id
)は、API 呼び出しを実行する必要がある組織を表すもので、すべての API リクエストのヘッダーとして必要です。このIDは、Adobe開発者コンソールで確認できます。「統合」タブで、特定の統合の概要セクションに移動し、クライアント資格情報の下のIDを探します。 Platformへの認証方法の詳しい説明については、認証のチュートリアルを参照してください。
API キーは、すべての API リクエストのヘッダーとして必要です。このファイルは、Adobeデベロッパーコンソールから入手できます。 コンソールの「統合」タブで、特定の統合の「概要」セクションに移動すると、「クライアント資格情報」の下にキーが表示されます。Platformに対する認証方法の詳しい説明については、認証のチュートリアルを参照してください。
アクセストークンは、すべての API 呼び出しの Authorization ヘッダーに必要です。IMS 組織の統合にアクセスできる場合は、curl
コマンドを使用して生成できます。アクセストークンは 24 時間のみ有効で、その後 API を使用し続けるためには新しいトークンを生成する必要があります。アクセストークンの生成について詳しくは、認証に関するチュートリアルを参照してください。
一部のPlatform APIエンドポイントは、特定のクエリを探し、応答で返された結果をフィルタリングするために、情報パラメーターを受け入れます。 リクエストパスに疑問符(?
)記号が付加され、その後に 1 つ以上のクエリーパラメーターが paramName=paramValue
形式で追加されます。1 回の呼び出しで複数のパラメーターを組み合わせる場合、アンパサンド(&
)を使用して個々のパラメーターを区切る必要があります。次の例は、複数のクエリーパラメーターを使用するリクエストがドキュメントでどのように表現されているかを示しています。
以下は、一般的に使用されるクエリーパラメーターの例です。
GET /tenant/schemas?orderby=title
GET /datasets?limit=36&start=10
GET /batches?createdAfter=1559775880000&orderBy=desc:created
特定のサービスまたはクエリで使用できるエンドポイントパラメーターの詳細については、サービス固有のドキュメントを参照してください。
Platform APIの多くのPATCH操作では、更新するJSONプロパティを示すためにJSONポインター文字列を使用します。 これらは通常、JSON パッチ 形式を使用してリクエストペイロードに含まれます。これらのテクノロジーに必要な構文について詳しくは、API の基本原則ガイドを参照してください。
Postman は、RESTful API への呼び出しを視覚化する便利なツールです。この投稿では、Postman を設定して自動的に認証を実行し、それを使用して API を利用する方法を説明します。Experience Platform
UI と API のどちらを使用しているかによって、次の必要システム構成が適用されます。
UI ベースの操作の場合:
API および開発者のインタラクションの場合:
以下は、Experience Platformサービスを使用する際に発生する可能性があるエラーのリストです。 個々のPlatformサービスのトラブルシューティングガイドについては、下のサービストラブルシューティングディレクトリを参照してください。
Experience Platform APIでは、次のステータスコードが検出される場合があります。 それぞれに様々な原因があり、本項で述べる説明は概して一般的なものです。個々のPlatformサービスの特定のエラーに関する詳細は、下のサービストラブルシューティングディレクトリを参照してください。
ステータスコード | 説明 | 考えられる原因 |
---|---|---|
400 | Bad request | リクエストが不適切に構築され、キー情報が欠落している、または正しくない構文が含まれていました。 |
401 | Authentication failed | リクエストが認証チェックに合格しませんでした。アクセストークンが見つからないか、無効です。詳しくは、以下の「OAuth トークンエラー」の節を参照してください。 |
403 | Forbidden | リソースが見つかりましたが、リソースを表示するための正しい資格情報がありません。 |
404 | Not found | リクエストされたリソースがサーバーで見つかりませんでした。リソースが削除されたか、リクエストされたパスが正しく入力されていない可能性があります。 |
500 | Internal server error | これはサーバーサイドのエラーです。同時に多数の呼び出しをおこなう場合、API の制限に達し、結果をフィルターする必要がある可能性があります。(詳しくは、フィルタリングデータのCatalog Service API開発者ガイドのサブガイドを参照してください)。 リクエストを再試行する前にしばらく待ち、問題が解決しない場合は管理者に問い合わせてください。 |
Platform内のすべてのAPI呼び出しには、特定のリクエストヘッダーが必要です。 個々のサービスに必要なヘッダーを確認するには、 API リファレンスのドキュメントを参照してください。必要な認証ヘッダーの値を確認するには、認証に関するチュートリアルを参照してください。API 呼び出しをおこなう際に、これらのヘッダーのいずれかが見つからないか無効な場合は、次のエラーが発生する可能性があります。
{
"error_code": "403010",
"message": "Oauth token is missing."
}
このエラーメッセージは、API リクエストに Authorization
ヘッダーがない場合に表示されます。再試行する前に、Authorization ヘッダーが有効なアクセストークンに含まれていることを確認してください。
{
"error_code": "401013",
"message": "Oauth token is not valid"
}
このエラーメッセージは、Authorization
ヘッダーに指定されたアクセストークンが無効な場合に表示されます。トークンが正しく入力されていることを確認するか、Adobe I/O コンソールで新しいトークンを生成します。
{
"error_code": "403000",
"message": "Api Key is required"
}
このエラーメッセージは、API リクエストに API キーヘッダー(x-api-key
)がない場合に表示されます。再試行する前に、ヘッダーが有効な API キーに含まれていることを確認してください。
{
"error_code": "403003",
"message": "Api Key is invalid"
}
このエラーメッセージは、指定された API キーヘッダー(x-api-key
)の値が無効な場合に表示されます。再試行する前に、キーが正しく入力されていることを確認してください。API キーがわからない場合は、Adobe I/O コンソールで確認できます。「統合」タブで 、特定の統合の「概要」セクションに移動すると、「クライアント資格情報」の下に API キーが表示されます。
{
"error_code": "400003",
"message": "Missing header"
}
このエラーメッセージは、IMS 組織ヘッダー(x-gw-ims-org-id
)が API リクエストに存在しない場合に表示されます。再試行する前に、IMS 組織の ID を含むヘッダーが含まれていることを確認してください。
{
"error_code": "403025",
"message": "Profile is not valid"
}
このエラーメッセージは、ユーザーまたは Adobe I/O 統合( ヘッダーのAuthorization
アクセストークンExperience Platformによって識別)が、x-gw-ims-org-id
ヘッダーで提供された IMS 組織に対して API を呼び出す権利がない場合に表示されます。再試行する前に、ヘッダーに IMS 組織の正しい ID が指定されていることを確認してください。組織 ID が不明な場合は、Adobe I/O コンソールで確認できます。「統合」タブで、特定の統合の「概要」セクションに移動すると、「クライアント資格情報」の下に ID が表示されます。
{
"type": "/placeholder/type/uri",
"status": 400,
"title": "BadRequestError",
"detail": "A valid content-type must be specified"
}
このエラーメッセージは、POST、PUT、PATCH リクエストの Content-Type
ヘッダーが無効か、見つからない場合に表示されます。ヘッダーがリクエストに含まれ、その値が application/json
であることを確認します。
以下は、Experience Platform APIのトラブルシューティングガイドとAPIリファレンスドキュメントのリストです。 各トラブルシューティングガイドは、個々のPlatformサービスに固有の問題に関するよくある質問と解決方法に対する回答を提供します。 API リファレンスドキュメントは、各サービスで使用可能なすべてのエンドポイントの包括的なガイドを提供し、受け取る可能性のあるリクエストの本文、応答、エラーコードのサンプルを示します。
サービス | API リファレンス | トラブルシューティング |
---|---|---|
アクセス制御 | アクセス制御 API | アクセス制御トラブルシューティングガイド |
Adobe Experience Platformでのデータ取得 | Data Ingestion API | Batch Ingestionのトラブルシューティング ガイドストリーミング取り込みのトラブルシューティングガイド |
Adobe Experience Platformデータサイエンスワークスペース | Sensei Machine Learning API | Data Science Workspace トラブルシューティングガイド |
Adobe Experience Platform のデータガバナンス | Policy Service API | |
Adobe Experience Platform ID サービス | Identity Service API | Identity Service トラブルシューティングガイド |
Adobe Experience Platform クエリサービス | Query Service API | Query Service トラブルシューティングガイド |
Adobe Experience Platform分類 | Segmentation API | |
Catalog Service | Catalog Service API | |
Experience Data Model (XDM) | Schema Registry API | XDM System FAQとトラブルシューティングガイド |
Flow Service (Sources および Destinations) | Flow Service API | |
Real-time Customer Profile | Real-time Customer Profile API | Profile トラブルシューティングガイド |
サンドボックス | サンドボックス API | サンドボックストラブルシューティングガイド |