ストリーミングセグメント化により、ほぼリアルタイムでイベントを評価

メモ

次のドキュメントでは、APIを使用したストリーミングセグメントの使用方法を説明します。 UIを使用したストリーミングセグメントの使用について詳しくは、『ストリー ミングセグメント化UI』ガイドを参照してください

セグメント化のストリーミング Adobe Experience Platform により、お客様はデータの豊富性に重点を置きながら、ほぼリアルタイムでセグメント化を行うことができます。 ストリーミングセグメント化では、セグメント化ジョブのスケジュールや実行の必要性を軽減し、データのストリーミング到着時にセグメントの認定が行わ Platformれるようになりました。 With this capability, most segment rules can now be evaluated as the data is passed into Platform, meaning segment membership will be kept up-to-date without running scheduled segmentation jobs.

メモ

ストリーミングセグメントは、プラットフォームにストリーミングされるデータを評価する場合にのみ使用できます。 つまり、バッチ取り込みによって取り込まれるデータは、ストリーミングセグメント化によって評価されず、夜間にスケジュールされたセグメント化ジョブと共に評価されます。

はじめに

This developer guide requires a working understanding of the various Adobe Experience Platform services involved with streaming segmentation. このチュートリアルを開始する前に、次のサービスのドキュメントを確認してください。

  • Real-time Customer Profile:複数のソースからの集計データに基づいて、リアルタイムで統一された消費者プロファイルを提供します。
  • Segmentation:データからセグメントやオーディエンスを作成する機能を提供し Real-time Customer Profile ます。
  • Experience Data Model (XDM):顧客体験データを Platform 整理する際に使用される標準化されたフレームワーク。

The following sections provide additional information that you will need to know in order to successfully make calls to Platform APIs.

API 呼び出し例の読み取り

この開発者ガイドは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切にフォーマットされたリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してください。Experience Platform

必須ヘッダーの値の収集

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

  • x-sandbox-name: {SANDBOX_NAME}
メモ

For more information on sandboxes in Platform, see the sandbox overview documentation.

ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。

  • Content-Type: application/json

特定のリクエストを完了するには、追加のヘッダーが必要な場合があります。このドキュメントの各例では、正しいヘッダーが表示されます。必要なヘッダーがすべて含まれるように、リクエスト例に特に注意してください。

ストリーミングセグメント化が有効なクエリタイプ

メモ

ストリーミングセグメントを機能させるには、組織でスケジュールされたセグメント化を有効にする必要があります。 スケジュール済みセグメントを有効にする方法については、「スケジュール済みセグメントを 有効にする」の節を参照してください。

ストリーミングセグメントを使用してセグメントを評価するには、クエリが次のガイドラインに従う必要があります。

クエリタイプ 詳細
受信ヒット 時間制限のない、単一の着信イベントを参照するセグメント定義。
相対時間枠内での着信ヒット 単一の着信イベントを参照するセグメント定義。
プロファイルのみ プロファイル属性のみを参照するセグメント定義。
プロファイルを参照する着信ヒット 時間制限のない、1つの着信イベント、および1つ以上のプロファイル属性を参照するセグメント定義。
相対的な時間枠内のプロファイルを参照する着信ヒット 1つの受信イベントと1つ以上のプロファイル属性を参照するセグメント定義。
プロファイルを参照する複数のイベント 過去24時間以内に複数のイベントを参照するセグメント定義 には 、1つ以上のプロファイル属性が含まれます。

次のシナリオでは、セグメント定義 、ストリーミングセグメントに対して有効になりません。

  • セグメント定義には、Adobe Audience Manager(AAM)のセグメントまたは特性が含まれます。
  • セグメント定義には、複数のエンティティ(マルチエンティティクエリ)が含まれます。

さらに、ストリーミングセグメント化を行う際には、次のようなガイドラインが適用されます。

クエリタイプ ガイドライン
単一イベントクエリ ルックバックウィンドウに制限はありません。
イベント履歴のあるクエリ
  • ルックバックウィンドウは 1日に制限されます
  • イベント間に厳密な時間順序条件 が存在する必要があります
  • 少なくとも1つの無効なイベントを持つクエリがサポートされます。 ただし、イベント全体を否定にする ことはできません

ストリーミングセグメントで有効になっているすべてのセグメントを取得

エンドポイントにGETリクエストを行うことで、IMS組織内でストリーミングセグメント化が有効になっているすべてのセグメントのリストを取得でき /segment/definitions ます。

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: {IMS_ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

正常な応答は、ストリーミングセグメント化対応 IMS 組織内セグメントの配列を返します。

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_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": "{IMS_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: {IMS_ORG}' \
  -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"
    }
}'
メモ

これは、標準の「セグメントの作成」リクエストです。 For more information about creating a segment definition, please read the tutorial on creating a segment.

応答

正常な応答は、新たに作成されたストリーミング対応セグメント定義の詳細を返します。

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "imsOrgId": "{IMS_ORG}",
    "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
}

スケジュールされた評価の有効化

ストリーミング評価が有効になったら、ベースラインを作成する必要があります(ベースラインの作成後、セグメントは常に最新の状態になります)。システムが自動的にベースライン設定を実行するには、スケジュールされた評価(「スケジュールされたセグメント化」とも呼ばれます)を有効にする必要があります。 スケジュール済みセグメントを使用すると、IMS組織は繰り返しのスケジュールに従って、セグメントを評価するために書き出しジョブを自動的に実行できます。

メモ

Scheduled evaluation can be enabled for sandboxes with a maximum of five (5) merge policies for XDM Individual Profile. If your organization has more than five merge policies for XDM Individual Profile within a single sandbox environment, you will not be able to use scheduled evaluation.

スケジュールの作成

/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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'
プロパティ 説明
name (必須)​スケジュールの名前。文字列である必要があります。
type (必須)​文字列形式のジョブタイプ。サポートされているタイプは batch_segmentationexport です。
properties (必須)​スケジュールに関連する追加のプロパティを含むオブジェクト。
properties.segments typebatch_segmentation と等しい場合は必須)["*"] を使用すると、すべてのセグメントが含まれます。
schedule (必須)​ジョブスケジュールを含む文字列。ジョブは 1 日に 1 回のみ実行するようにスケジュールできます。つまり、24 時間の間に 2 回以上実行するようにジョブをスケジュールすることはできません。例(0 0 1 * * ?)は、ジョブが毎日1:00:00 UTC にトリガーされることを示しています。詳しくは、CRON 式形式のドキュメントを参照してください。
state (オプション)​スケジュールの状態を含む文字列。使用可能な値は activeinactive です。デフォルト値は inactive です。IMS 組織で作成できるスケジュールは 1 つだけです。スケジュールを更新する手順は、このチュートリアルの後半で説明します。

応答

成功した応答は、新しく作成したスケジュールの詳細を返します。

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{IMS_ORG}",
    "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 を含めることで、スケジュールを有効にする(stateactive に設定する)ことができます。

API 形式

POST /config/schedules/{SCHEDULE_ID}

リクエスト

次のリクエストでは、スケジュールの stateactive に更新するために、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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

応答

更新が成功すると、空の応答本文と HTTP ステータス 204(No Content)が返されます。

同じ操作を使用して、前のリクエストの「値」を「inactive」に置き換えることで、スケジュールを無効にできます。

次の手順

新しいセグメントと既存のセグメントの両方でストリーミングセグメント化を有効にし、スケジュールされたセグメント化を有効にしてベースラインを開発し、定期評価を実行したので、組織のセグメントの作成を開始できます。

Adobe Experience Platform ユーザーインターフェイスを使用して同様のアクションを実行し、セグメントを操作する方法については、『セグメントビルダーユーザーガイド』を参照してください。

このページ