外部オーディエンスエンドポイント
外部オーディエンスを使用すると、外部ソースからAdobe Experience Platformにプロファイルデータをアップロードできます。 Segmentation Service API の /external-audience
エンドポイントを使用すると、外部オーディエンスをExperience Platformに取り込んだり、詳細を表示したり、外部オーディエンスを更新したり、外部オーディエンスを削除したりできます。
はじめに
/core/ais
ではなく、/core/ups
がプレフィックスとして付けられています。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}
外部オーディエンスを作成 create-audience
/external-audience/
エンドポイントに POST リクエストを実行することで、外部オーディエンスを作成できます。
API 形式
POST /external-audience/
リクエスト
code language-shell |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
name |
文字列 | 外部オーディエンスの名前。 |
description |
文字列 | 外部オーディエンスのオプションの説明。 |
customAudienceId |
文字列 | 外部オーディエンスのオプションの識別子。 |
fields |
オブジェクトの配列 |
フィールドとそのデータタイプのリスト。 フィールドのリストを作成する際には、次の項目を追加できます。
|
sourceSpec |
オブジェクト |
外部オーディエンスが配置されている情報を含むオブジェクト。 このオブジェクトを使用する場合、次の情報を含める 必要があります。
|
ttlInDays |
整数 | 外部オーディエンスのデータ有効期限(日数)。 この値は 1~90 に設定できます。 デフォルトでは、データの有効期限は 30 日に設定されています。 |
audienceType |
文字列 | 外部オーディエンスのオーディエンスタイプ。 現在は、people のみがサポートされています。 |
originName |
文字列 | 必須 オーディエンスの接触チャネル。 これは、オーディエンスがどこから来たかを示します。外部オーディエンスの場合は、CUSTOM_UPLOAD を使用する必要があります。 |
namespace |
文字列 | オーディエンスの名前空間。 デフォルトでは、この値は CustomerAudienceUpload に設定されています。 |
labels |
文字列の配列 | 外部オーディエンスに適用されるアクセス制御ラベル。 使用可能なアクセス制御ラベルについて詳しくは、 データ使用ラベルの用語集を参照してください。 |
tags |
文字列の配列 | 外部オーディエンスに適用するタグ。 タグについて詳しくは、 タグ管理ガイドを参照してください。 |
応答
応答が成功すると、HTTP ステータス 202 が、新しく作成された外部オーディエンスの詳細と共に返されます。
code language-json |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
operationId |
文字列 | 操作の ID。 その後、この ID を使用して、オーディエンスの作成ステータスを取得できます。 |
operationDetails |
オブジェクト | 外部オーディエンスの作成のために送信したリクエストの詳細を含むオブジェクト。 |
name |
文字列 | 外部オーディエンスの名前。 |
description |
文字列 | 外部オーディエンスの説明。 |
fields |
オブジェクトの配列 | フィールドとそのデータタイプのリスト。 この配列は、外部オーディエンスで必要なフィールドを決定します。 |
sourceSpec |
オブジェクト | 外部オーディエンスが配置されている情報を含むオブジェクト。 |
ttlInDays |
整数 | 外部オーディエンスのデータ有効期限(日数)。 この値は 1~90 に設定できます。 デフォルトでは、データの有効期限は 30 日に設定されています。 |
audienceType |
文字列 | 外部オーディエンスのオーディエンスタイプ。 |
originName |
文字列 | 必須 オーディエンスの接触チャネル。 これは、オーディエンスのソースを示します。 |
namespace |
文字列 | オーディエンスの名前空間。 |
labels |
文字列の配列 | 外部オーディエンスに適用されるアクセス制御ラベル。 使用可能なアクセス制御ラベルについて詳しくは、 データ使用ラベルの用語集を参照してください。 |
オーディエンス作成ステータスの取得 retrieve-status
外部オーディエンス送信のステータスを取得するには、/external-audiences/operations
エンドポイントにGET リクエストを実行し、外部オーディエンス作成応答から受け取った操作の ID を指定します。
API 形式
GET /external-audiences/operations/{OPERATION_ID}
{OPERATION_ID}
id
値。リクエスト
code language-shell |
---|
|
応答
応答が成功すると、HTTP ステータス 200 が、外部オーディエンスのタスクステータスの詳細と共に返されます。
code language-json |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
operationId |
文字列 | 取得する操作の ID。 |
status |
文字列 | 操作のステータス。 SUCCESS 、FAILED 、PROCESSING のいずれかの値を指定できます。 |
operationDetails |
オブジェクト | オーディエンスの詳細を含むオブジェクト。 |
audienceId |
文字列 | 操作によって送信される外部オーディエンスの ID。 |
createdBy |
文字列 | 外部オーディエンスを作成したユーザーの ID。 |
createdAt |
ロングエポックタイムスタンプ | 外部オーディエンスを作成するリクエストが送信された際のタイムスタンプ(秒)。 |
updatedBy |
文字列 | オーディエンスを最後に更新したユーザーの ID。 |
updatedAt |
ロングエポックタイムスタンプ | オーディエンスが最後に更新された際のタイムスタンプ(秒)。 |
外部オーディエンスの更新 update-audience
audienceId
が必要です。 audienceId
エンドポイントへの呼び出しが成功すると、GET /external-audiences/operations/{OPERATION_ID}
を取得できます。/external-audience
エンドポイントに対してPATCH リクエストを実行し、リクエストパスにオーディエンスの ID を指定することで、外部オーディエンスのフィールドを更新できます。
このエンドポイントを使用する場合、次のフィールドを更新できます。
- オーディエンスの説明
- フィールドレベルのアクセス制御ラベル
- オーディエンスレベルのアクセス制御ラベル
- オーディエンスのデータ有効期限
このエンドポイントを使用してフィールドを更新すると リクエストしたフィールドのコンテンツを置き換え ます。
API 形式
PATCH /external-audience/{AUDIENCE_ID}
リクエスト
code language-shell |
---|
|
table 0-row-3 1-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
description |
文字列 | 外部オーディエンスの更新された説明。 |
さらに、次のパラメーターを更新できます。
table 0-row-3 1-row-3 2-row-3 3-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
labels |
配列 | オーディエンスのアクセスラベルの更新されたリストを含む配列。 使用可能なアクセス制御ラベルについて詳しくは、 データ使用ラベルの用語集を参照してください。 |
fields |
オブジェクトの配列 | 外部オーディエンスのフィールドおよび関連するラベルを含む配列。 PATCH リクエストにリストされているフィールドのみが更新されます。 使用可能なアクセス制御ラベルについて詳しくは、 データ使用ラベルの用語集を参照してください。 |
ttlInDays |
整数 | 外部オーディエンスのデータ有効期限(日数)。 この値は 1~90 に設定できます。 |
応答
応答が成功すると、HTTP ステータス 200 が、更新された外部オーディエンスの詳細と共に返されます。
code language-json |
---|
|
オーディエンスの取り込みを開始 start-audience-ingestion
audienceId
が必要です。 audienceId
エンドポイントへの呼び出しが成功すると、GET /external-audiences/operations/{OPERATION_ID}
を取得できます。オーディエンス ID を指定しながら次のエンドポイントに対して POST リクエストを実行することで、オーディエンスの取り込みを開始できます。
API 形式
POST /external-audience/{AUDIENCE_ID}/runs
リクエスト
次のリクエストは、外部オーディエンスに対して取り込み実行をトリガーします。
code language-shell |
---|
|
table 0-row-3 1-row-3 2-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
dataFilterStartTime |
エポックタイムスタンプ | 必須 処理するファイルを選択するためにフローを実行する開始時間を指定する範囲。 |
dataFilterEndTime |
エポックタイムスタンプ | 処理するファイルを選択するためにフローを実行する終了時刻を指定する範囲。 |
応答
応答が成功すると、HTTP ステータス 200 が、取り込み実行の詳細と共に返されます。
code language-json |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
audienceName |
文字列 | 取り込み実行を開始するオーディエンスの名前。 |
audienceId |
文字列 | オーディエンスの ID。 |
runId |
文字列 | 開始した取得実行の ID。 |
differentialIngestion |
ブール値 | 前回の取り込み以降の違いに基づいて、取り込みが部分取り込みか、完全なオーディエンス取り込みかを決定するフィールド。 |
dataFilterStartTime |
エポックタイムスタンプ | 処理されたファイルを選択するためにフローを実行する開始時間を指定する範囲。 |
dataFilterEndTime |
エポックタイムスタンプ | 処理されたファイルを選択するためにフローを実行する終了時刻を指定する範囲。 |
createdAt |
ロングエポックタイムスタンプ | 外部オーディエンスを作成するリクエストが送信された際のタイムスタンプ(秒)。 |
createdBy |
文字列 | 外部オーディエンスを作成したユーザーの ID。 |
特定のオーディエンス取り込みステータスの取得 retrieve-ingestion-status
audienceId
と取り込み実行 ID の runId
の両方が必要です。 audienceId
エンドポイントへの呼び出しが成功すると、GET /external-audiences/operations/{OPERATION_ID}
を取得でき、runId
エンドポイントの以前の呼び出しが成功すると、POST /external-audience/{AUDIENCE_ID}/runs
を取得できます。オーディエンス ID と実行 ID の両方を提供しながら、次のエンドポイントに対してGET リクエストを実行することで、オーディエンス取り込みのステータスを取得できます。
API 形式
GET /external-audience/{AUDIENCE_ID}/runs/{RUN_ID}
リクエスト
次のリクエストは、外部オーディエンスの取り込みステータスを取得します。
code language-shell |
---|
|
応答
応答が成功すると、HTTP ステータス 200 が、外部オーディエンス取り込みの詳細と共に返されます。
code language-json |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
audienceName |
文字列 | オーディエンスの名前。 |
audienceId |
文字列 | オーディエンスの ID。 |
runId |
文字列 | 取り込み実行の ID。 |
status |
文字列 | 取得実行のステータス。 可能なステータスには、SUCCESS および FAILED があります。 |
differentialIngestion |
ブール値 | 前回の取り込み以降の違いに基づいて、取り込みが部分取り込みか、完全なオーディエンス取り込みかを決定するフィールド。 |
dataFilterStartTime |
エポックタイムスタンプ | 処理されたファイルを選択するためにフローを実行する開始時間を指定する範囲。 |
dataFilterEndTime |
エポックタイムスタンプ | 処理されたファイルを選択するためにフローを実行する終了時刻を指定する範囲。 |
createdAt |
ロングエポックタイムスタンプ | 外部オーディエンスを作成するリクエストが送信された際のタイムスタンプ(秒)。 |
createdBy |
文字列 | 外部オーディエンスを作成したユーザーの ID。 |
details |
オブジェクトの配列 |
取り込み実行の詳細を含むオブジェクト。
|
オーディエンス取り込み実行のリスト list-ingestion-runs
audienceId
が必要です。 audienceId
エンドポイントへの呼び出しが成功すると、GET /external-audiences/operations/{OPERATION_ID}
を取得できます。オーディエンス ID を指定した際に、次のエンドポイントに対してGET リクエストを行うことで、選択した外部オーディエンスに対して実行されたすべての取り込みを取得できます。 複数のパラメーターを使用する場合は、アンパサンド(&
)で区切ります。
API 形式
GET /external-audience/{AUDIENCE_ID}/runs
リクエスト
次のリクエストでは、外部オーディエンスに対するすべての取り込み実行を取得します。
code language-shell |
---|
|
応答
応答が成功すると、HTTP ステータス 200 が、指定された外部オーディエンスに対する取り込み実行のリストと共に返されます。
code language-json |
---|
|
table 0-row-3 1-row-3 | ||
---|---|---|
プロパティ | タイプ | 説明 |
runs |
オブジェクト | オーディエンスに属する取り込み実行のリストを含むオブジェクト。 このオブジェクトについて詳しくは、 取り込みステータスの取得を参照してください。 |
外部オーディエンスの削除 delete-audience
audienceId
が必要です。 audienceId
エンドポイントへの呼び出しが成功すると、GET /external-audiences/operations/{OPERATION_ID}
を取得できます。オーディエンス ID を指定した状態で次のエンドポイントに対してDELETE リクエストを行うことで、外部オーディエンスを削除できます。
API 形式
DELETE /external-audience/{AUDIENCE_ID}
リクエスト
次のリクエストは、指定された外部オーディエンスを削除します。
code language-shell |
---|
|
応答
応答が成功すると、HTTP ステータス 204 が、空の応答本文と共に返されます。
次の手順 next-steps
このガイドを読むことで、Experience Platform API を使用して外部オーディエンスを作成、管理および削除する方法について、理解が深まりました。 Experience Platform UI で外部オーディエンスを使用する方法については、 オーディエンスポータルドキュメントを参照してください。
付録 appendix
次の節では、外部オーディエンス API を使用する場合に使用可能なエラーコードを示します。
BAD_REQUEST
BAD_REQUEST
UNAUTHORIZED
UNAUTHORIZED
imsOrgId
が指定されました。UNAUTHORIZED
NOT_FOUND
DUPLICATE_RESOURCE
UNPROCESSABLE_ENTITY
INTERNAL_SERVER_ERROR
BAD_GATEWAY