オーディエンスエンドポイント
オーディエンスは、類似の行動や特徴を共有する人々の集まりです。 これらの人物のコレクションは、Adobe Experience Platformを使用するか、外部ソースから生成できます。 Segmentation API の /audiences
エンドポイントを使用すると、オーディエンスをプログラムにより取得、作成、更新、削除できます。
はじめに
このガイドで使用するエンドポイントは、Adobe Experience Platform Segmentation Service API の一部です。 続行する前に、 はじめる前にを参照して、必要なヘッダーやサンプル API 呼び出しの読み取り方法など、API の呼び出しを正常に実行するために必要な重要な情報を確認してください。
オーディエンスのリストの取得 list
/audiences
エンドポイントに対してGETリクエストを行うことで、組織のすべてのオーディエンスのリストを取得できます。
API 形式
/audiences
エンドポイントは、結果を絞り込むのに役立つ、複数のクエリパラメーターをサポートしています。これらのパラメーターはオプションですが、リソースをリストする際の高価なオーバーヘッドを削減するために、使用することを強くお勧めします。 パラメーターを指定せずにこのエンドポイントを呼び出すと、組織で使用可能なすべてのオーディエンスが取得されます。 複数のパラメーターを使用する場合は、アンパサンド(&
)で区切ります。
GET /audiences
GET /audiences?{QUERY_PARAMETERS}
property=audienceId
クエリパラメーターと組み合わせて使用すると、非アクティブなオーディエンス が返され す。オーディエンスのリストを取得する際には、次のクエリパラメーターを使用できます。
start
start=5
limit
limit=10
sort
attributeName:[desc/asc]
の形式で記述されます。sort=updateTime:desc
property
property=
の形式で記述されますproperty=audienceId==test-audience-id
name
name=Sample
description
description=Test Description
entityType
entityType=_xdm.context.account
リクエスト
次のリクエストでは、組織で作成された最後の 2 つのオーディエンスを取得します。
code language-shell |
---|
|
応答
応答に成功すると、HTTP ステータス 200 が、組織内で JSON として作成されたオーディエンスのリストと共に返されます。
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 12-row-3 13-row-3 14-row-3 15-row-3 16-row-3 17-row-3 18-row-3 | ||
---|---|---|
プロパティ | オーディエンスタイプ | 説明 |
id |
両方 | オーディエンスのシステム生成の読み取り専用識別子。 |
audienceId |
両方 | オーディエンスが Platform で生成されたオーディエンスの場合、これは id と同じ値です。 オーディエンスが外部で生成される場合、この値はクライアントから提供されます。 |
schema |
両方 | オーディエンスのエクスペリエンスデータモデル(XDM)スキーマ。 |
imsOrgId |
両方 | オーディエンスが属する組織の ID。 |
sandbox |
両方 | オーディエンスが属するサンドボックスに関する情報。 サンドボックスについて詳しくは、 サンドボックスの概要を参照してください。 |
name |
両方 | オーディエンスの名前。 |
description |
両方 | オーディエンスの説明。 |
expression |
Platform で生成 | オーディエンスのProfile Query Language(PQL)式。 PQL式について詳しくは、PQL式ガイドを参照してください。 |
mergePolicyId |
Platform で生成 | オーディエンスが関連付けられている結合ポリシーの ID。 結合ポリシーについて詳しくは、結合ポリシーガイドを参照してください。 |
evaluationInfo |
Platform で生成 | オーディエンスの評価方法を表示します。 考えられる評価方法には、バッチ、同期(ストリーミング)または連続(エッジ)があります。 評価方法について詳しくは、 セグメント化の概要を参照してください。 |
dependents |
両方 | 現在のオーディエンスに依存するオーディエンス ID の配列。 これは、セグメントのセグメントであるオーディエンスを作成する場合に使用されます。 |
dependencies |
両方 | オーディエンスが依存するオーディエンス ID の配列。 これは、セグメントのセグメントであるオーディエンスを作成する場合に使用されます。 |
type |
両方 | オーディエンスが Platform で生成されたものか、外部で生成されたオーディエンスかを表示する、システムで生成されたフィールド。 使用可能な値は SegmentDefinition および ExternalSegment です。 SegmentDefinition は、Platform で生成されたオーディエンスを指し、ExternalSegment は、Platform で生成されなかったオーディエンスを指します。 |
originName |
両方 | オーディエンスの接触チャネルの名前を参照するフィールド。 Platform で生成されたオーディエンスの場合、この値は REAL_TIME_CUSTOMER_PROFILE になります。 Audience Orchestration で生成されたオーディエンスの場合、この値は AUDIENCE_ORCHESTRATION になります。 Adobe Audience Managerで生成されたオーディエンスの場合、この値は AUDIENCE_MANAGER になります。 外部で生成されたその他のオーディエンスの場合、この値は CUSTOM_UPLOAD になります。 |
createdBy |
両方 | オーディエンスを作成したユーザーの ID。 |
labels |
両方 | オーディエンスに関連するオブジェクトレベルのデータ使用と属性ベースのアクセス制御ラベル。 |
namespace |
両方 | オーディエンスが属する名前空間。 使用可能な値は、AAM 、AAMSegments 、AAMTraits 、AEPSegments などです。 |
linkedAudienceRef |
両方 | 他のオーディエンス関連システムへの識別子を含むオブジェクト。 |
新しいオーディエンスの作成 create
/audiences
エンドポイントにPOSTリクエストを実行することで、新しいオーディエンスを作成できます。
API 形式
POST /audiences
リクエスト
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
---|---|
プロパティ | 説明 |
name |
オーディエンスの名前。 |
description |
オーディエンスの説明。 |
type |
オーディエンスが Platform で生成されたものか、外部で生成されたものかを表示するフィールド。 使用可能な値は SegmentDefinition および ExternalSegment です。 SegmentDefinition は、Platform で生成されたオーディエンスを指し、ExternalSegment は、Platform で生成されなかったオーディエンスを指します。 |
expression |
オーディエンスのProfile Query Language(PQL)式。 PQL式について詳しくは、PQL式ガイドを参照してください。 |
schema |
オーディエンスのエクスペリエンスデータモデル(XDM)スキーマ。 |
labels |
オーディエンスに関連するオブジェクトレベルのデータ使用と属性ベースのアクセス制御ラベル。 |
応答
応答に成功すると、HTTP ステータス 200 と、新しく作成されたオーディエンスに関する情報が返されます。
code language-json |
---|
|
指定したオーディエンスの検索 get
/audiences
エンドポイントに対してGETリクエストを実行し、取得するオーディエンスの ID をリクエストパスで指定することで、特定のオーディエンスに関する詳細な情報を検索できます。
API 形式
GET /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}
id
のフィールドであり、audienceId
のフィールドでは ありません 注意してください。リクエスト
code language-shell |
---|
|
応答
応答に成功すると、HTTP ステータス 200 と、指定されたオーディエンスに関する情報が返されます。
code language-json |
---|
|
オーディエンスの更新 put
特定のエンドポイントに対してPUTリクエストを実行し、リクエストパスで更新するオーディエンスの ID を指定することで、/audiences
定のオーディエンスを更新(上書き)できます。
API 形式
PUT /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}
id
のフィールドであり、audienceId
のフィールドでは ありません 注意してください。リクエスト
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 | |
---|---|
プロパティ | 説明 |
audienceId |
オーディエンスの ID。 外部で生成されたオーディエンスの場合、この値はユーザーによって指定される場合があります。 |
name |
オーディエンスの名前。 |
namespace |
オーディエンスの名前空間。 |
description |
オーディエンスの説明。 |
type |
オーディエンスが Platform で生成されたものか、外部で生成されたオーディエンスかを表示する、システムで生成されたフィールド。 使用可能な値は SegmentDefinition および ExternalSegment です。 SegmentDefinition は、Platform で生成されたオーディエンスを指し、ExternalSegment は、Platform で生成されなかったオーディエンスを指します。 |
lifecycleState |
オーディエンスのステータス。使用可能な値は、draft 、published 、inactive です。 draft は、オーディエンスが作成されたとき、オーディエンスが公開されたと published 、オーディエンスがアクティブでなくなった inactive を表します。 |
datasetId |
オーディエンスデータを検索できるデータセットの ID。 |
labels |
オーディエンスに関連するオブジェクトレベルのデータ使用と属性ベースのアクセス制御ラベル。 |
応答
応答が成功すると、HTTP ステータス 200 が、新しく更新されたオーディエンスの詳細と共に返されます。 オーディエンスの詳細は、Platform で生成されたオーディエンスか、外部で生成されたオーディエンスかによって異なることに注意してください。
code language-json |
---|
|
オーディエンスの削除 delete
特定のオーディエンスを削除するには、/audiences
エンドポイントにDELETEリクエストを実行し、リクエストパスで削除するオーディエンスの ID を指定します。
API 形式
DELETE /audiences/{AUDIENCE_ID}
{AUDIENCE_ID}
id
のフィールドであり、audienceId
のフィールドでは ありません 注意してください。リクエスト
code language-shell |
---|
|
応答
リクエストが成功した場合、HTTP ステータス 204 が返され、メッセージは返されません。
複数のオーディエンスの取得 bulk-get
/audiences/bulk-get
エンドポイントに対してPOSTリクエストを行い、取得するオーディエンスの ID を指定することで、複数のオーディエンスを取得できます。
API 形式
POST /audiences/bulk-get
リクエスト
code language-shell |
---|
|
応答
応答に成功すると、HTTP ステータス 207 と、リクエストされたオーディエンスの情報が返されます。
code language-json |
---|
|
次の手順
このガイドを読むことで、Adobe Experience Platform API を使用してオーディエンスを作成、管理および削除する方法について、理解が深まりました。 UI を使用した Audience Management について詳しくは、 セグメント化 UI ガイドを参照してください。