セグメント定義エンドポイント
Adobe Experience Platformでは、プロファイルのグループから特定の属性や動作のグループを定義するセグメント定義を作成できます。 セグメント定義は、Profile Query Language (PQL)で記述されたクエリをカプセル化するオブジェクトです。 セグメント定義は、オーディエンスを作成するためのプロファイルに適用されます。 このオブジェクト(セグメント定義)は、PQL述語とも呼ばれます。 PQLの述語は、Real-Time Customer Profile に提供するレコードまたは時系列データに関連する条件に基づいて、セグメント定義のルールを定義します。 PQL クエリの記述について詳しくは、PQL ガイドを参照してください。
このガイドでは、セグメント定義をより深く理解するための情報を提供し、API を使用して基本的なアクションを実行するためのサンプル API 呼び出しが含まれています。
はじめに
このガイドで使用するエンドポイントは、Adobe Experience Platform Segmentation Service API の一部です。 続行する前に、 はじめる前にを参照して、必要なヘッダーやサンプル API 呼び出しの読み取り方法など、API の呼び出しを正常に実行するために必要な重要な情報を確認してください。
セグメント定義のリストの取得 list
/segment/definitions
エンドポイントに対してGETリクエストを行うことで、組織のすべてのセグメント定義のリストを取得できます。
API 形式
/segment/definitions
エンドポイントは、結果を絞り込むのに役立つ、複数のクエリパラメーターをサポートしています。これらのパラメーターはオプションですが、高価なオーバーヘッドの削減に役立てるため、使用することを強くお勧めします。 パラメーターを指定せずにこのエンドポイントを呼び出すと、組織で使用可能なすべてのセグメント定義が取得されます。 複数のパラメーターを使用する場合は、アンパサンド(&
)で区切ります。
GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}
クエリパラメータ
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 | ||
---|---|---|
パラメーター | 説明 | 例 |
start |
返されるセグメント定義の開始オフセットを指定します。 | start=4 |
limit |
返される、1 ページあたりのセグメント定義の数を指定します。 | limit=20 |
page |
どのページからセグメント定義の結果を表示するかを指定します。 | page=5 |
sort |
結果を並べ替えるフィールドを指定します。 [attributeName]:[desc/asc] の形式で記述されます。 |
sort=updateTime:desc |
evaluationInfo.continuous.enabled |
セグメント定義でストリーミングを有効にするかどうかを指定します。 | evaluationInfo.continuous.enabled=true |
リクエスト
以下のリクエストは、組織内に投稿された最後の 2 つのセグメント定義を取得します。
code language-shell |
---|
|
応答
応答に成功すると、HTTP ステータス 200 が、指定した組織のセグメント定義のリストと共に JSON として返されます。
code language-json |
---|
|
新しいセグメント定義の作成 create
新しいセグメント定義を作成するには、/segment/definitions
エンドポイントに POST リクエストを実行します。
API 形式
POST /segment/definitions
リクエスト
新しいセグメント定義を作成する際は、pql/text
形式または pql/json
形式で作成できます。
accordion | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
セグメント定義を作成するリクエストの例。 | ||||||||||||||||||||||
|
accordion | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
セグメント定義を作成するリクエストの例。 | ||||||||||||||||||||||
|
応答
リクエストが成功した場合は、新しく作成したセグメント定義の詳細と HTTP ステータス 200 が返されます。
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 | |
---|---|
プロパティ | 説明 |
id |
新しく作成したセグメント定義のシステム生成 ID。 |
evaluationInfo |
セグメント定義が受ける評価のタイプを示すオブジェクト。 バッチ、ストリーミング(連続とも呼ばれます)、エッジ(同期とも呼ばれます)のセグメント化があります。 |
特定のセグメント定義の取得 get
特定のセグメント定義に関する詳細な情報を取得するには、/segment/definitions
エンドポイントにGETリクエストを実行し、取得するセグメント定義の ID をリクエストパスで指定します。
API 形式
GET /segment/definitions/{SEGMENT_ID}
{SEGMENT_ID}
id
値。リクエスト
code language-shell |
---|
|
応答
リクエストが成功した場合は、特定のセグメント定義についての詳細情報と HTTP ステータス 200 が返されます。
code language-json |
---|
|
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 9-row-2 | |
---|---|
プロパティ | 説明 |
id |
セグメント定義のシステム生成の読み取り専用 ID。 |
name |
セグメント定義を参照するための一意の名前。 |
schema |
セグメント内のエンティティに関連付けられているスキーマ。 id か name のどちらかのフィールドで構成されます。 |
expression |
セグメント定義に関するフィールド情報を含んだエンティティ。 |
expression.type |
式タイプを指定します。現時点では、「PQL」のみサポートされています。 |
expression.format |
値内の式の構造を示します。現時点では、次の形式がサポートされています。
|
expression.value |
expression.format に指定されたタイプに適合する式です。 |
description |
人間にとってわかりやすい、定義の説明。 |
evaluationInfo |
セグメント定義が受ける評価のタイプ、バッチ、ストリーミング(連続とも呼ばれます)、またはエッジ(同期とも呼ばれます)を示すオブジェクト。 |
セグメント定義の一括取得 bulk-get
/segment/definitions/bulk-get
エンドポイントに対してPOSTリクエストを実行し、リクエスト本文にセグメント定義の id
値を指定することで、指定された複数のセグメント定義に関する詳細な情報を取得できます。
API 形式
POST /segment/definitions/bulk-get
リクエスト
code language-shell |
---|
|
table 0-row-2 1-row-2 | |
---|---|
プロパティ | 説明 |
ids |
取得するセグメント定義の ID を格納するオブジェクトを含む配列。 |
応答
応答に成功すると、HTTP ステータス 207 と、リクエストされたセグメント定義が返されます。
code language-json |
---|
|
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 9-row-2 | |
---|---|
プロパティ | 説明 |
id |
セグメント定義のシステム生成の読み取り専用 ID。 |
name |
セグメント定義を参照するための一意の名前。 |
schema |
セグメント内のエンティティに関連付けられているスキーマ。 id か name のどちらかのフィールドで構成されます。 |
expression |
セグメント定義に関するフィールド情報を含んだエンティティ。 |
expression.type |
式タイプを指定します。現時点では、「PQL」のみサポートされています。 |
expression.format |
値内の式の構造を示します。現時点では、次の形式がサポートされています。
|
expression.value |
expression.format に指定されたタイプに適合する式です。 |
description |
人間にとってわかりやすい、定義の説明。 |
evaluationInfo |
セグメント定義が受ける評価のタイプ、バッチ、ストリーミング(連続とも呼ばれます)、またはエッジ(同期とも呼ばれます)を示すオブジェクト。 |
特定のセグメント定義の削除 delete
リクエストパスで削除するセグメント定義の ID をリク /segment/definitions
ストエンドポイントに指定して、DELETEリクエストを行うことで、特定のセグメント定義を削除するようにリクエストできます。
API 形式
DELETE /segment/definitions/{SEGMENT_ID}
{SEGMENT_ID}
id
の値。リクエスト
code language-shell |
---|
|
応答
リクエストが成功した場合、HTTP ステータス 200 が返され、メッセージは返されません。
特定のセグメント定義の更新
特定のセグメント定義を更新するには、/segment/definitions
エンドポイントにPATCHリクエストを実行し、リクエストパスで更新するセグメント定義の ID を指定します。
API 形式
PATCH /segment/definitions/{SEGMENT_ID}
{SEGMENT_ID}
id
の値。リクエスト
次のリクエストは、勤務先住所の国を米国からカナダに更新します。
code language-shell |
---|
|
応答
リクエストが成功した場合は、更新したセグメント定義の詳細と HTTP ステータス 200 が返されます。
code language-json |
---|
|
セグメント定義を変換
セグメント定義を pql/text
と pql/json
の間で変換するか、/segment/conversion
エンドポイントに対してPOSTリクエストを行って pql/json
を pql/text
に変換できます。
API 形式
POST /segment/conversion
リクエスト
次のリクエストは、セグメント定義の形式を pql/text
から pql/json
に変更します。
code language-shell |
---|
|
応答
応答に成功すると、HTTP ステータス 200 が、新しく変換されたセグメント定義の詳細と共に返されます。
code language-json |
---|
|
次の手順
このガイドを読むことで、セグメント定義の仕組みについて理解が深まりました。 セグメントの作成について詳しくは、「セグメントの作成 チュートリアルを参照しください。