ストリーミングセグメント化を使用してほぼリアルタイムでイベントを評価する
Adobe Experience Platform でのストリーミングセグメント化では、データの豊富さに重点を置きながら、ほぼリアルタイムでセグメント化を実行できます。ストリーミングセグメント化を使用すると、ストリーミングデータが Platform に到着する際にセグメントの選定が行われるので、セグメント化ジョブをスケジュールして実行する必要がなくなります。 この機能により、データが Platform に渡される際に、ほとんどのセグメントルールが評価されるようになりました。つまり、スケジュールに沿ったセグメント化ジョブを実行しなくても、セグメントメンバーシップが常に最新の状態に保たれます。
はじめに
この開発者ガイドでは、ストリーミングセグメント化に関連する様々な Adobe Experience Platform サービスについて、実際に理解している必要があります。このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。
- Real-Time Customer Profile:複数のソースからの集計データに基づいて、統合されたリアルタイムの顧客プロファイルを提供します。
- Segmentation: Real-Time Customer Profile データ。
- Experience Data Model (XDM):Platform が、カスタマーエクスペリエンスデータを整理する際に使用する、標準化されたフレームワーク。
以下の節では、Platform API を正しく呼び出すために知っておく必要がある追加情報を示します。
API 呼び出し例の読み取り
この開発者ガイドは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーの値の収集
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization: Bearer
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されています。Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
- x-sandbox-name:
{SANDBOX_NAME}
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、次のような追加ヘッダーが必要です。
- Content-Type: application/json
特定のリクエストを完了するには、追加のヘッダーが必要な場合があります。このドキュメントの各例では、正しいヘッダーが表示されます。必要なヘッダーがすべて含まれるように、リクエスト例に特に注意してください。
ストリーミングセグメント化が有効なクエリタイプ query-types
ストリーミングセグメント化を使用してセグメント定義を評価するには、クエリを次のガイドラインに従う必要があります。
次のシナリオでは、セグメント定義はストリーミングセグメント化に対して有効に なりません。
- セグメント定義には、Adobe Audience Manager(AAM)のセグメントまたは特性が含まれます。
- セグメント定義には複数のエンティティ(複数エンティティクエリ)が含まれます。
- セグメント定義には、単一のイベントと
inSegment
イベントの組み合わせが含まれます。- ただし、
inSegment
イベントに含まれるセグメントがプロファイルのみの場合、セグメント定義はストリーミングセグメント化に対して有効に なります。
- ただし、
ストリーミングセグメント化を行う場合は、次のガイドラインに従ってください。
- ルックバックウィンドウは 1 日 に制限されています。
- イベント間に厳密な時間順序条件が存在する 必要があります。
- 少なくとも 1 つの否定イベントを含むクエリがサポートされています。 ただし、イベント全体を否定することは できません。
セグメント定義を変更して、ストリーミングセグメント化の条件を満たさなくなった場合、セグメント定義は自動的に「ストリーミング」から「バッチ」に切り替わります。
また、セグメントの選定解除は、セグメントの選定と同様に、リアルタイムで発生します。その結果、プロファイルがセグメント定義の対象にならなくなった場合、そのプロファイルはただちに非認定になります。 例えば、セグメント定義で「過去 3 時間で赤い靴を購入したすべてのユーザー」という要求があった場合、3 時間後に、最初にセグメント定義で選定されたすべてのプロファイルが無効になります。
ストリーミングセグメント化に対して有効なすべてのセグメント定義を取得
組織内でストリーミングセグメント化が有効になっているすべてのセグメント定義のリストを取得するには、 /segment/definitions
endpoint.
API 形式
ストリーミングが有効なセグメント定義を取得するには、クエリパラメーターを含める必要があります evaluationInfo.continuous.enabled=true
リクエストパス内で使用します。
GET /segment/definitions?evaluationInfo.continuous.enabled=true
リクエスト
curl -X GET \
'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
正常な応答は、組織内でストリーミングセグメント化が有効なセグメント定義の配列を返します。
{
"segments": [
{
"id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": " People who are NOT on their homepage ",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572029711000,
"updateEpoch": 1572029712000,
"updateTime": 1572029712000
},
{
"id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "",
"sandboxName": "",
"type": "production",
"default": true
},
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"sortField": "creationTime",
"sort": "desc",
"pageSize": 2,
"limit": 100
},
"link": {}
}
ストリーミングが有効なセグメント定義の作成
セグメント定義が 上記のストリーミングセグメント化タイプ.
API 形式
POST /segment/definitions
リクエスト
curl -X POST \
https://platform.adobe.io/data/core/ups/segment/definitions \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
}
}'
応答
正常な応答は、新たに作成されたストリーミング対応セグメント定義の詳細を返します。
{
"id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"type": "production",
"default": true
},
"name": "Homepage_continuous",
"description": "People who are on their homepage - continuous",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
},
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true,
},
"synchronous": {
"enabled": false
}
},
"creationTime": 1572021085000,
"updateEpoch": 1572021086000,
"updateTime": 1572021086000
}
スケジュールされた評価の有効化 enable-scheduled-segmentation
ストリーミング評価を有効にしたら、ベースラインを作成する必要があります(ベースラインの作成後、セグメント定義は常に最新の状態になります)。 システムが自動的にベースライン化を実行するには、まず、スケジュールされた評価(スケジュールされたセグメント化とも呼ばれます)を最初に有効にする必要があります。スケジュールに沿ったセグメント化を使用すると、繰り返しスケジュールに従って、書き出しジョブを自動的に実行し、セグメント定義を評価できます。
スケジュールの作成
/config/schedules
エンドポイントに対して POST リクエストを実行することにより、スケジュールを作成し、スケジュールをトリガーする必要がある特定の時間を指定することができます。
API 形式
POST /config/schedules
リクエスト
次のリクエストは、ペイロードで提供された仕様に基づいて新しいスケジュールを作成します。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/schedules \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "{SCHEDULE_NAME}",
"type": "batch_segmentation",
"properties": {
"segments": ["*"]
},
"schedule": "0 0 1 * * ?",
"state": "inactive"
}'
name
type
batch_segmentation
と export
です。properties
properties.segments
type
次と等しい batch_segmentation
) 使用 ["*"]
は、すべてのセグメント定義が含まれるようにします。schedule
0 0 1 * * ?
)は、ジョブが毎日 1:00:00 UTC にトリガーされることを意味します。詳しくは、セグメント化のスケジュールのドキュメント内で、cron 式形式に関する付録を確認してください。state
active
と inactive
です。デフォルト値は inactive
です。1 つの組織が作成できるスケジュールは 1 つだけです。 スケジュールを更新する手順は、このチュートリアルの後半で説明します。応答
成功した応答は、新しく作成したスケジュールの詳細を返します。
{
"id": "cd585edf-962d-420d-94ad-3be03e619ac2",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "{SCHEDULE_NAME}",
"state": "inactive",
"type": "batch_segmentation",
"schedule": "0 0 1 * * ?",
"properties": {
"segments": [
"*"
]
},
"createEpoch": 1568267948,
"updateEpoch": 1568267948
}
スケジュールの有効化
デフォルトでは、作成(POST)リクエスト本文で state
プロパティが active
に設定されていない限り、スケジュールは作成時に非アクティブになります。/config/schedules
エンドポイントに対して PATCH リクエストを実行し、パスにスケジュールの ID を含めることで、スケジュールを有効にする(state
を active
に設定する)ことができます。
API 形式
POST /config/schedules/{SCHEDULE_ID}
リクエスト
次のリクエストでは、スケジュールの state
を active
に更新するために、JSON パッチの形式を使用しています。
curl -X POST \
https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '[
{
"op": "add",
"path": "/state",
"value": "active"
}
]'
応答
更新が成功すると、空の応答本文と HTTP ステータス 204(No Content)が返されます。
同じ操作を使用して、前のリクエストの「値」を「inactive」に置き換えることで、スケジュールを無効にできます。
次の手順
これで、ストリーミングセグメント化の新しいセグメント定義と既存のセグメント定義の両方を有効にし、スケジュールされたセグメント化を有効にして、ベースラインを作成し、定期的な評価を実行できるようになりました。
Adobe Experience Platformユーザーインターフェイスを使用して同様のアクションを実行し、セグメント定義を操作する方法については、 セグメントビルダーユーザーガイド.
付録
次の節では、ストリーミングセグメント化に関するよくある質問を一覧表示しています。
ストリーミングセグメント化の「選定解除」もリアルタイムで発生しますか。
ほとんどのインスタンスでは、ストリーミングセグメント化の選定解除はリアルタイムで発生します。ただし、セグメントのセグメントを使用するストリーミングセグメント定義では、 not はリアルタイムで未認定で、24 時間後に不適格と見なされます。
ストリーミングセグメント化はどのデータで機能しますか。
ストリーミングセグメント化は、ストリーミングソースを使用して取り込まれたすべてのデータに対して機能します。 バッチベースのソースを使用して取り込まれたセグメントは、ストリーミングセグメント化の対象となっている場合でも、毎晩評価されます。タイムスタンプが 24 時間より古いシステムにストリーミングされたイベントは、後続のバッチジョブで処理されます。
セグメント定義は、バッチまたはストリーミングによるセグメント化としてどのように定義されますか。
セグメント定義は、クエリタイプとイベント履歴期間の組み合わせに基づいて、バッチまたはストリーミングによるセグメント化として定義されます。 ストリーミングセグメントとして評価されるセグメント定義のリストは、 ストリーミングセグメント化のクエリタイプの節.
セグメントに inSegment
式と直接の単一イベントチェーンの 両方 が含まれる場合、ストリーミングセグメント化の対象にはなりません。このセグメント定義をストリーミングセグメント化の対象として認定する場合は、直接の単一イベントチェーンを独自のセグメント定義にする必要があります。
「過去 X 日間」の下の数がセグメント定義の詳細セクション内でゼロのままの間、「合計認定済み」セグメント定義の数が増加し続けるのはなぜですか?
合計認定セグメント定義の数は、日別のセグメント化ジョブから取得されます。このジョブには、バッチセグメント定義とストリーミングセグメント定義の両方に適合するオーディエンスが含まれます。 この値は、バッチセグメント定義とストリーミングセグメント定義の両方で表示されます。
「過去 X 日間」の下にある数値は、ストリーミングセグメント化の対象となるオーディエンスの数 のみ を表し、データをシステムにストリーミングしそのストリーミング定義に照合してカウントする場合に のみ 増加します。この値は、 のみ ストリーミングセグメントの定義に関する説明を表示します。 その結果、この値 may バッチセグメント定義の場合は 0 と表示されます。
その結果、「過去 X 日間」の下の数がゼロで、線グラフもゼロをレポートしている場合は、 not は、任意のプロファイルを、そのセグメント定義に該当するシステムにストリーミングしました。
セグメント定義が使用可能になるまで、どれくらいかかりますか。
セグメント定義が使用可能になるまでに最大 1 時間かかります。
ストリーミングされるデータに制限はありますか。
ストリーミングデータをストリーミングセグメント化で使用するには、ここで 必須 間には、ストリーミングされるイベントの間隔を指定します。 同じ秒数内にストリーミングされるイベントが多すぎる場合、Platform はこれらのイベントをボット生成データとして扱い、破棄されます。 ベストプラクティスとして、以下が必要です。 少なくとも データが適切に使用されていることを確認するために、イベントデータの間の 5 秒間隔。