使用串流獲取API串流時間序列資料

本教學課程將協助您開始使用Adobe Experience Platform Data Ingestion Service API中的串流獲取API。

快速入門

本教學課程需具備各種Adobe Experience Platform服務的工作知識。 開始本教學課程之前,請先檢閱下列服務的檔案:

  • Experience Data Model (XDM):組織體驗資料的 Platform 標準化架構。
  • Real-time Customer Profile:根據來自多個來源的匯總資料,即時提供統一的消費者設定檔。
  • Schema Registry開發人員指南:涵蓋API每個可用端點的完整指 Schema Registry 南,以及如何呼叫這些端點。這包括了解本教學課程中呼叫中顯示的{TENANT_ID},以及了解如何建立結構描述(用於建立資料集以進行擷取)。

此外,本教學課程需要您已建立串流連線。 有關建立流連接的詳細資訊,請參閱建立流連接教程

以下小節提供您將需要知道的其他資訊,以便成功呼叫串流獲取API。

讀取範例API呼叫

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

收集必要標題的值

若要呼叫Platform API,您必須先完成authentication tutorial。 完成驗證教學課程後,將提供所有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

根據XDM ExperienceEvent類別撰寫結構

若要建立資料集,您必須先建立實作XDM ExperienceEvent類別的新架構。 有關如何建立架構的詳細資訊,請參閱Schema Registry API開發人員指南

API格式

POST /schemaregistry/tenant/schemas

要求

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas
  -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 '{
    "type": "object",
    "title": "{SCHEMA_NAME}",
    "description": "{SCHEMA_DESCRIPTION}",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce"
        },
        {  
         "$ref":"https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
        }
    ],
    "meta:immutableTags": [
        "union"
    ]
}'
屬性 說明
title 要用於架構的名稱。 此名稱必須是唯一的。
description 您正在建立之結構的有意義說明。
meta:immutableTags 在此範例中, union標籤可用來將您的資料保留至Real-time Customer Profile

回應

成功的回應會傳回HTTP狀態201,並包含新建立結構的詳細資訊。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
    "meta:resourceType": "schemas",
    "version": "1",
    "type": "object",
    "title": "{SCHEMA_NAME}",
    "description": "{SCHEMA_DESCRIPTION}",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/experienceevent-commerce",
        "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
        "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
        "https://ns.adobe.com/xdm/context/experienceevent"
    ],
    "imsOrg": "{IMS_ORG}",
    "meta:immutableTags": [
        "union"
    ],
    "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
    "required": [
        "@id",
        "xdm:timestamp"
    ],
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/experienceevent",
        "https://ns.adobe.com/xdm/data/time-series",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
        "https://ns.adobe.com/xdm/context/experienceevent-commerce",
        "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
    "meta:registryMetadata": {
        "repo:createDate": 1551229957987,
        "repo:lastModifiedDate": 1551229957987,
        "xdm:createdClientId": "{CLIENT_ID}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    },
    "meta:tenantNamespace": "{NAMESPACE}"
}
屬性 說明
{TENANT_ID} 此ID可確保您建立的資源與IMS組織中的資源命名正確,且完整無缺。 有關租戶ID的詳細資訊,請閱讀架構註冊表指南

請注意$idversion屬性,因為建立資料集時將會同時使用這些屬性。

為架構設定主標識描述符

接下來,將標識描述符添加到以上建立的架構,使用工作電子郵件地址屬性作為主標識符。 執行此動作會產生兩個變更:

  1. 工作電子郵件地址將成為必填欄位。 這表示未使用此欄位傳送的訊息將無法驗證,且不會擷取。

  2. Real-time Customer Profile 會使用工作電子郵件地址做為識別碼,協助匯整該個人的詳細資訊。

請求

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '{
    "@type":"xdm:descriptorIdentity",
    "xdm:sourceProperty":"/_experience/campaign/message/profileSnapshot/workEmail/address",
    "xdm:property":"xdm:code",
    "xdm:isPrimary":true,
    "xdm:namespace":"Email",
    "xdm:sourceSchema":"{SCHEMA_REF_ID}",
    "xdm:sourceVersion":1
}
屬性 說明
{SCHEMA_REF_ID} 構建架構時先前收到的$id。 看起來應該像這樣:"https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}"
注意

身分命名空間代碼

請確定程式碼有效 — 上述範例使用「電子郵件」(標準身分命名空間)。 您可在Identity服務常見問題集中找到其他常用的標準身分識別命名空間。

如果您想要建立自訂命名空間,請依照身分命名空間概述中概述的步驟操作。

回應

成功的回應會傳回HTTP狀態201,其中包含新建立之架構主要身分命名空間的相關資訊。

{
    "xdm:property": "xdm:code",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "xdm:namespace": "Email",
    "@type": "xdm:descriptorIdentity",
    "xdm:sourceVersion": 1,
    "xdm:isPrimary": true,
    "xdm:sourceProperty": "/_experience/campaign/message/profileSnapshot/workEmail/address",
    "@id": "ec31c09e0906561861be5a71fcd964e29ebe7923b8eb0d1e",
    "meta:containerId": "tenant",
    "version": "1",
    "imsOrg": "{IMS_ORG}"
}

為時間序列資料建立資料集

建立結構後,您需要建立資料集以內嵌記錄資料。

注意

此資料集將透過設定適當的標籤來啟用​Real-time Customer Profile​和​Identity

API格式

POST /catalog/dataSets

要求

curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
  -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 '{
    "name": "{DATASET_NAME}",
    "description": "{DATASET_DESCRIPTION}",
    "schemaRef": {
        "id": "{SCHEMA_REF_ID}",
        "contentType": "application/vnd.adobe.xed-full+json;version=1"
    },
    "tags": {
        "unifiedIdentity": ["enabled:true"],
        "unifiedProfile": ["enabled:true"]
    }
}'

回應

成功的回應會傳回HTTP狀態201,以及包含新建立資料集ID的陣列,格式為@/dataSets/{DATASET_ID}

[
    "@/dataSets/5e72608b10f6e318ad2dee0f"
]

建立串流連線

建立結構和資料集後,您需要建立串流連線才能內嵌資料。

有關建立流連接的詳細資訊,請參閱建立流連接教程

將時間序列資料內嵌至串流連線

建立資料集、串流連線和資料流後,您可以內嵌XDM格式的JSON記錄,以內嵌Platform內的時間序列資料。

API格式

POST /collection/{CONNECTION_ID}?syncValidation=true
參數 說明
{CONNECTION_ID} 新建立的串流連線的id值。
syncValidation 供開發使用的選用查詢參數。 如果設為true,則可用於立即反饋以確定請求是否成功發送。 預設情況下,此值會設為false。 請注意,如果您將此查詢參數設為true,則請求的速率將限制為每分鐘60次/次/ CONNECTION_ID

要求

使用或不使用來源名稱,即可將時間序列資料擷取至串流連線。

以下範例要求將缺少來源名稱的時間序列資料內嵌至Platform。 如果資料缺少來源名稱,則會從串流連線定義新增來源ID。

重要

您將需要生成自己的xdmEntity._idxdmEntity.timestamp。 產生ID的好方法是在資料準備中使用UUID函式。 有關UUID函式的更多資訊,請參閱資料準備函式指南xdmEntity._id屬性表示記錄本身的唯一標識符,​表示記錄所在的人員或設備的唯一ID。 人員或裝置ID將在任何指派為結構之人員或裝置識別碼的屬性中指定。

xdmEntity._idxdmEntity.timestamp是時間序列資料的唯一必填欄位。 此外,下列API呼叫​​需要任何驗證標題。

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
        "schemaRef": {
            "id": "{SCHEMA_REF_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version=1"
        },
        "flowId": "{FLOW_ID}",
        "datasetId": "{DATASET_ID}"
    },
    "body": {
        "xdmMeta": {
            "schemaRef": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
                "contentType": "application/vnd.adobe.xed-full+json;version=1"
            }
        },
        "xdmEntity":{
            "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
            "timestamp": "2019-02-23T22:07:01Z",
            "environment": {
                "browserDetails": {
                    "userAgent": "Mozilla\/5.0 (Windows NT 5.1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/29.0.1547.57 Safari\/537.36 OPR\/16.0.1196.62",
                    "acceptLanguage": "en-US",
                    "cookiesEnabled": true,
                    "javaScriptVersion": "1.6",
                    "javaEnabled": true
                },
                "colorDepth": 32,
                "viewportHeight": 799,
                "viewportWidth": 414
            },
            "productListItems": [
                {
                    "SKU": "CC",
                    "name": "Fernie Snow",
                    "quantity": 30,
                    "priceTotal": 7.8
                }
            ],
            "commerce": {
                "productViews": {
                    "value": 1
                }
            },
            "_experience": {
                "campaign": {
                    "message": {
                        "profileSnapshot": {
                            "workEmail":{
                                "address": "janedoe@example.com"
                            }
                        }
                    }
                }
            }
        }
    }
}'

如果要包括源名稱,以下示例將說明如何包括它。

    "header": {
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version=1"
        },
        "imsOrgId": "{IMS_ORG}",
        "datasetId": "{DATASET_ID}",
        "source": {
            "name": "Sample source name"
        }
    }

回應

成功的響應返回HTTP狀態200,並包含新流Profile的詳細資訊。

{
    "inletId": "{CONNECTION_ID}",
    "xactionId": "1584479347507:2153:240",
    "receivedTimeMs": 1584479347507,
    "syncValidation": {
        "status": "pass"
    }
}
屬性 說明
{CONNECTION_ID} 先前建立的串流連線的inletId
xactionId 在伺服器端為您剛傳送的記錄產生唯一識別碼。 此ID有助於Adobe通過各種系統和調試跟蹤此記錄的生命週期。
receivedTimeMs:顯示接收請求的時間的時間戳記(以毫秒為單位)。
syncValidation.status 由於新增了查詢參數syncValidation=true,因此會出現此值。 如果驗證成功,狀態將為pass

擷取新擷取的時間序列資料

若要驗證先前擷取的記錄,您可以使用Profile Access API擷取時間序列資料。 您可以使用向/access/entities端點提出的GET要求,並使用選用的查詢參數來完成此操作。 可使用多個參數,以&符號分隔。"

注意

如果未定義合併策略ID,且schema.namerelatedSchema.name_xdm.context.profile,Profile Access將獲取​所有​相關身份。

API格式

GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email
參數 說明
schema.name 必填。 您正在存取的架構的名稱。
relatedSchema.name 必填。 由於您正在訪 _xdm.context.experienceevent問,因此此值指定與時間序列事件相關的配置檔案實體的架構。
relatedEntityId 相關實體的ID。 若有提供,您也必須提供實體命名空間。
relatedEntityIdNS 您嘗試擷取之ID的命名空間。

要求

curl -X GET \
  https://platform.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email \
  -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}"

回應

成功的回應會傳回HTTP狀態200,並包含所請求實體的詳細資訊。 如您所見,這與先前擷取的時間序列資料相同。

{
    "_page": {
        "orderby": "timestamp",
        "start": "9af5adcc-db9c-4692-b826-65d3abe68c22",
        "count": 1,
        "next": ""
    },
    "children": [
        {
            "relatedEntityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
            "entityId": "9af5adcc-db9c-4692-b826-65d3abe68c22",
            "timestamp": 1582495621000,
            "entity": {
                "environment": {
                    "browserDetails": {
                        "javaScriptVersion": "1.6",
                        "cookiesEnabled": true,
                        "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
                        "acceptLanguage": "en-US",
                        "javaEnabled": true
                    },
                    "colorDepth": 32,
                    "viewportHeight": 799,
                    "viewportWidth": 414
                },
                "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
                "commerce": {
                    "productViews": {
                        "value": 1
                    }
                },
                "productListItems": [
                    {
                        "name": "Fernie Snow",
                        "quantity": 30,
                        "SKU": "CC",
                        "priceTotal": 7.8
                    }
                ],
                "_experience": {
                    "campaign": {
                        "message": {
                            "profileSnapshot": {
                                "workEmail": {
                                    "address": "janedoe@example.com"
                                }
                            }
                        }
                    }
                },
                "timestamp": "2020-02-23T22:07:01Z"
            },
            "lastModifiedAt": "2020-03-18T18:51:19Z"
        }
    ],
    "_links": {
        "next": {
            "href": ""
        }
    }
}

後續步驟

閱讀本檔案後,您現在可以了解如何使用串流連線將記錄資料內嵌至Platform。 您可以嘗試使用不同值進行更多呼叫並擷取更新的值。 此外,您也可以透過Platform UI開始監控擷取的資料。 如需詳細資訊,請參閱監控資料擷取指南。

如需串流獲取的詳細資訊,請參閱串流獲取概述

本頁內容