評估和存取區段結果

本檔案提供使用Segmentation API評估區段及存取區段結果的教學課程。

快速入門

本教學課程需要妥善了解建立受眾區段時涉及的各種Adobe Experience Platform服務。 開始本教學課程之前,請先檢閱下列服務的檔案:

必要標題

本教學課程也需要您完成authentication tutorial,才能成功呼叫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

評估區段

開發、測試並儲存區段定義後,您就可以透過排程評估或隨需評估來評估區段。

排程評估 (也稱為「排程區段」)可讓您建立在特定時間執行匯出作業的循環排程,而 隨需 評估則涉及建立區段工作以立即建立對象。各步驟的步驟如下所述。

如果您尚未完成使用區段API教學課程建立區段,或使用區段產生器建立區段定義,請先完成此操作,再繼續進行本教學課程。

計畫評估

透過排程的評估,您的IMS組織可以建立循環排程以自動執行匯出作業。

注意

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

建立排程

通過向/config/schedules端點發出POST請求,可以建立調度並包括應觸發該調度的特定時間。

有關使用此端點的更多詳細資訊,請參見schedules endpoint guide

啟用排程

預設情況下,建立時,排程會非作用中,除非在建立(POST)請求正文中將state屬性設定為active。 您可以向/config/schedules端點發出PATCH請求,並在路徑中包含調度的ID,以啟用調度(將state設定為active)。

有關使用此端點的更多詳細資訊,請參見schedules endpoint guide

更新排程時間

/config/schedules端點發出PATCH請求並在路徑中包含排程的ID,可以更新排程計時。

有關使用此端點的更多詳細資訊,請參見schedules endpoint guide

隨選評估

隨需評估可讓您建立區段工作,以便隨時產生受眾區段。 與排程評估不同,這只會在要求時發生,且不會重複執行。

建立區段作業

區段工作是建立新受眾區段的非同步程式。 它會參考區段定義,以及任何控制Real-time Customer Profile如何合併設定檔片段之重疊屬性的合併原則。 區段工作成功完成後,您可以收集區段的各種資訊,例如處理期間可能發生的任何錯誤,以及對象的最終大小。

您可以透過向Real-time Customer Profile API中的/segment/jobs端點提出POST要求,以建立新的區段作業。

有關使用此端點的更多詳細資訊,請參見segment作業端點指南

查找段作業狀態

您可以對特定區段作業使用id來執行查閱請求(GET),以檢視作業的目前狀態。

有關使用此端點的更多詳細資訊,請參見segment作業端點指南

解譯區段結果

成功執行區段作業時,會針對包含在區段中的每個設定檔更新segmentMembership對應。 segmentMembership 也會儲存擷取至的任何預先評估對象區段,以 Platform便與其他解決方案(例如) Adobe Audience Manager整合。

下列範例顯示每個個別設定檔記錄的segmentMembership屬性看起來是什麼樣子:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "53cba6b2-a23b-454a-8069-fc41308f1c0f": {
        "lastQualificationTime": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      }
    },
    "Email": {
      "abcd@adobe.com": {
        "lastQualificationTime": "2017-09-26T15:52:25+00:00",
        "status": "exited"
      }
    }
  }
}
屬性 說明
lastQualificationTime 建立區段成員資格斷言以及設定檔輸入或退出區段時的時間戳記。
status 目前請求中區段參與率的狀態。 必須等於下列其中一個已知值:
  • existing:實體繼續在分部中。
  • realized:實體正在輸入區段。
  • exited:實體正在退出區段。

存取區段結果

您可透過下列兩種方式之一存取區段作業的結果:您可以存取個別設定檔,或將整個對象匯出至資料集。

以下各節將更詳細地介紹這些選項。

查詢設定檔

如果您知道要存取的特定設定檔,可使用Real-time Customer Profile API進行存取。 使用設定檔API🔗教學課程的存取即時客戶設定檔資料,提供存取個別設定檔的完整步驟。

匯出區段

分段工作成功完成後(status屬性的值為「SUCCEEDED」),您可以將對象匯出至資料集,以便存取資料集並加以處理。

匯出對象需要下列步驟:

建立目標資料集

匯出對象時,必須先建立目標資料集。 請務必正確設定資料集,以確保匯出成功。

其中一項主要考量事項為資料集所依據的結構(以下API範例請求中為schemaRef.id)。 若要匯出區段,資料集必須以XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union)為基礎。 聯合結構是系統產生的唯讀結構,會匯總共用相同類別之結構的欄位(在此例中是XDM個別設定檔類別)。 有關聯合查看架構的詳細資訊,請參閱Schema Registry開發人員指南🔗的 Real-time Customer Profile(即時客戶配置檔案)部分。

建立必要資料集的方式有兩種:

  • 使用API: 本教學課程後續步驟概述如何建立使用API參考 XDM Individual Profile Union Schema 的資料 Catalog 集。
  • 使用UI: 若要使用使 Adobe Experience Platform 用者介面建立參考聯合結構的資料集,請依照UI教學課程中的步驟操作,然後回到本教學課程,繼續執行產生受眾設定檔 的步驟 🔗

如果您已有相容的資料集且知道其ID,則可直接進入產生對象設定檔的步驟。

API格式

POST /dataSets

要求

下列請求會建立新資料集,提供裝載中的設定參數。

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -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": "Segment Export",
    "schemaRef": {
        "id": "https://ns.adobe.com/xdm/context/profile__union",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'
屬性 說明
name 資料集的描述性名稱。
schemaRef.id 與資料集關聯的聯合檢視(結構)ID。

回應

成功的回應會傳回一個陣列,內含新建立資料集的唯讀、系統產生的唯一ID。 若要成功匯出受眾成員,需要正確設定的資料集ID。

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

產生對象成員的設定檔

在您擁有持續存在的資料集後,您可以建立匯出工作,在Real-time Customer Profile API中向/export/jobs端點提出POST要求,並針對您要匯出的區段提供資料集ID和區段資訊,以保留對象成員至資料集。

有關使用此端點的更多詳細資訊,請參見export jobs endpoint guide

監視導出進度

作為導出作業進程,可以通過向/export/jobs端點發出GET請求並在路徑中包括導出作業的id來監視其狀態。 status欄位返回值「SUCCEEDED」後,導出作業即告完成。

有關使用此端點的更多詳細資訊,請參見export jobs endpoint guide

後續步驟

匯出成功後,您的資料即可在Experience Platform的Data Lake內使用。 然後,您可以使用Data Access API,使用與匯出相關聯的batchId存取資料。 根據區段的大小,資料可能是區塊,而批次可能包含數個檔案。

有關如何使用Data Access API訪問和下載批處理檔案的逐步說明,請遵循資料訪問教程

您也可以使用Adobe Experience Platform Query Service存取成功匯出的區段資料。 使用UI或RESTful API Query Service可讓您對Data Lake內的資料寫入、驗證及執行查詢。

如需如何查詢受眾資料的詳細資訊,請檢閱Query Service上的檔案。

本頁內容