使用串流分段功能,即時評估事件

注意

下列檔案說明如何使用API使用串流分段。 有關使用UI使用串流分段的資訊,請閱讀串流分段UI指南

Adobe Experience Platform上的串流分段可讓客戶近乎即時地進行分段,同時專注於資料的豐富性。 透過串流分段,現在當串流資料進入Platform時,會進行分段資格設定,以減輕排程和執行分段工作的需求。 有了這項功能,現在可評估大部分區段規則,因為資料會傳入Platform,這表示區段成員資格會保持最新,而不會執行排程的區段工作。

注意

串流區段只能用來評估串流至Platform的資料。 換言之,透過批次擷取所擷取的資料不會透過串流分段來評估,而且會與每夜排程的分段工作一起評估。

快速入門

本開發人員指南要求您對串流區段相關的各種Adobe Experience Platform服務有正確的瞭解。 在開始本教學課程之前,請先閱讀下列服務的檔案:

以下各節提供您必須知道的其他資訊,以便成功呼叫Platform API。

讀取範例API呼叫

本開發人員指南提供範例API呼叫,以示範如何格式化您的請求。 這些包括路徑、必要標題和正確格式化的請求負載。 也提供API回應中傳回的範例JSON。 如需範例API呼叫檔案中所用慣例的詳細資訊,請參閱Experience Platform疑難排解指南中如何讀取範例API呼叫一節。

收集必要標題的值

若要呼叫Platform API,您必須先完成驗證教學課程。 完成驗證教學課程後,所有Experience Platform API呼叫中每個所需標題的值都會顯示在下面:

  • 授權:載體{ACCESS_TOKEN}
  • x-api-key:{API_KEY}
  • x-gw-ims-org-id:{IMS_ORG}

Experience Platform中的所有資源都隔離到特定的虛擬沙盒。 對Platform API的所有請求都需要一個標題,該標題指定要在中執行操作的沙盒的名稱:

  • x-sandbox-name:{SANDBOX_NAME}
注意

如需Platform中沙盒的詳細資訊,請參閱沙盒概述檔案

所有包含裝載(POST、PUT、PATCH)的請求都需要額外的標題:

  • 內容類型:application/json

完成特定要求可能需要額外的標題。 本檔案的每個範例都會顯示正確的標題。 請特別注意範例要求,以確保包含所有必要的標題。

啟用串流分段的查詢類型

注意

您需要為組織啟用排程的分段,才能使串流分段正常運作。 有關啟用計劃分段的資訊,請參閱啟用計劃分段區段

若要使用串流分段來評估區段,查詢必須符合下列准則。

查詢類型 詳細資料
傳入點擊 任何區段定義,是指沒有時間限制的單一傳入事件。
在相對時間視窗內傳入點擊 任何參照單一傳入事件的區段定義。
含時間視窗的傳入點擊 任何區段定義,是指具有時間視窗的單一傳入事件。
僅限描述檔 任何僅指描述檔屬性的區段定義。
參照描述檔的傳入點擊 任何區段定義,是指單一傳入事件(無時間限制)以及一或多個描述檔屬性。
在相對時間視窗內參照描述檔的傳入點擊 任何區段定義,指單一傳入事件和一或多個描述檔屬性。
區段 包含一或多個批次或串流區段的任何區段定義。 注意:如 果使用區段,則每24小時就會發生描述 檔取消資格
參考描述檔的多個事件 在過去24小時內參照多個事件​且(可選)的區段定義具有一個或多個描述檔屬性。

在下列情況下,區段定義將​not​啟用串流區段:

  • 區段定義包含Adobe Audience Manager(AAM)區段或特徵。
  • 區段定義包括多個實體(多實體查詢)。

此外,執行串流區段時,也會套用一些准則:

查詢類型 准則
單一事件查詢 回顧視窗沒有限制。
具有事件歷史記錄的查詢
  • 回顧視窗限制為​一天
  • 事件之間存在嚴格的時間順序條件​必須
  • 支援具有至少一個否定事件的查詢。 但是,整個事件​cannot​是否定。

擷取所有啟用串流區段的區段

您可以向/segment/definitions端點提出GET請求,以擷取IMS組織內啟用串流分段的所有區段清單。

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"
    }
}'
注意

這是標準的「建立區段」請求。 如需建立區段定義的詳細資訊,請閱讀有關建立區段的教學課程。

回應

成功的回應會傳回新建立的啟用串流的區段定義詳細資料。

{
    "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組織可以遵循循環排程,自動執行匯出工作以評估區段。

注意

對於XDM Individual Profile最多可啟用五(5)個合併策略的沙盒,可啟用計畫評估。 如果您的組織在單一沙盒環境中有超過5個XDM Individual Profile的合併原則,您將無法使用排程的評估。

建立排程

通過向/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 (等於時需 type 要) batch_segmentation使["*"] 可確保包含所有區段。
schedule (必要)包 含工作排程的字串。作業只能排程為每天執行一次,這表示您無法排程作業在24小時期間執行多次。 顯示的示例(0 0 1 * * ?)表示每天在1:00:00 UTC觸發作業。 如需詳細資訊,請參閱cron運算式格式檔案。
state (選用)包 含排程狀態的字串。可用值:activeinactive。 預設值為 inactive。IMS組織只能建立一個排程。 本教學課程稍後將提供更新排程的步驟。

回應

成功的回應會傳回新建立之排程的詳細資料。

{
    "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,可以啟用調度(將state設定為active)。

API格式

POST /config/schedules/{SCHEDULE_ID}

要求

以下請求使用JSON修補程式格式,以便將排程的state更新為active

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(無內容)。

使用相同的操作可以禁用調度,方法是將上一個請求中的"value"替換為"inactive"。

後續步驟

現在您已啟用新區段和現有區段的串流區段,並啟用排程區段以建立基準並執行循環評估,您就可以開始為組織建立可串流化的區段。

若要瞭解如何使用Adobe Experience Platform使用者介面執行類似動作及使用區段,請造訪區段產生器使用指南

本頁內容