使用串流獲取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的詳細資訊，請閱讀架構註冊表指南。

請注意$id和version屬性，因為建立資料集時將會同時使用這些屬性。

為架構設定主標識描述符

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

工作電子郵件地址將成為必填欄位。這表示未使用此欄位傳送的訊息將無法驗證，且不會擷取。
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._id和xdmEntity.timestamp。產生ID的好方法是在資料準備中使用UUID函式。有關UUID函式的更多資訊，請參閱資料準備函式指南。 xdmEntity._id屬性表示記錄本身的唯一標識符，不表示記錄所在的人員或設備的唯一ID。人員或裝置ID將在任何指派為結構之人員或裝置識別碼的屬性中指定。

xdmEntity._id和xdmEntity.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.name或relatedSchema.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開始監控擷取的資料。如需詳細資訊，請參閱監控資料擷取指南。

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

adobe.com 上的資源

Cms Cloud Dynamic Media Cross Channel Marketing Web Analytics Programmatic Tv Performance Optimization

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

快速入門

讀取範例API呼叫

收集必要標題的值

根據XDM ExperienceEvent類別撰寫結構

為架構設定主標識描述符

請求

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

建立串流連線

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

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

後續步驟

adobe.com 上的資源

本頁內容

檢視下一個:

學習

說明文件

社群

技術支援

資源

Adobe 帳戶

Adobe