文件 Experience Platform Data Ingestion 指南

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

Last update: Thu May 25 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
Data Ingestion

建立對象：

Developer

本教學課程將幫助您開始使用串流獲取API (屬於Adobe Experience Platform的一部分) Data Ingestion Service API。

快速入門

本教學課程需要各種Adobe Experience Platform服務的實際操作知識。在開始本教學課程之前，請檢閱下列服務的檔案：

Experience Data Model (XDM)：作為依據的標準化架構 Platform 組織體驗資料。
Real-Time Customer Profile：根據來自多個來源的彙總資料，即時提供統一的消費者設定檔。
Schema Registry開發人員指南：涵蓋每個可用端點的完整指南 Schema Registry API以及如何對其發出呼叫。這包括瞭解您的 {TENANT_ID}，會在本教學課程中的呼叫中顯示，並且瞭解如何建立結構（用於建立資料集以供擷取）。

此外，本教學課程要求您已建立串流連線。如需建立串流連線的詳細資訊，請參閱建立串流連線教學課程.

使用平台API

如需如何成功呼叫Platform API的詳細資訊，請參閱以下指南中的 Platform API快速入門.

根據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: {ORG_ID}' \
  -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": "{ORG_ID}",
    "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": "{ORG_ID}",
    "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可用來確保您建立的資源能正確建立名稱空間，並包含在您的組織內。如需租使用者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: {ORG_ID}' \
  -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}"

NOTE

URL 身分名稱空間程式碼

請確定程式碼有效 — 上述範例使用「email」，這是標準身分名稱空間。其他常用的標準身分名稱空間可在以下網址找到： Identity Service常見問題集.

如果您想要建立自訂名稱空間，請依照身分名稱空間總覽.

回應

成功的回應會傳回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": "{ORG_ID}"
}

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

建立結構描述後，您需要建立資料集以擷取記錄資料。

NOTE

此資料集將啟用 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: {ORG_ID}' \
  -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 是時間序列資料的必填欄位。此 xdmEntity._id 屬性代表記錄本身的唯一識別碼， not 其紀錄所在之人員或裝置的唯一ID。

您將需要產生您自己的 xdmEntity._id 和 xdmEntity.timestamp 重新擷取記錄時，以維持一致的方式擷取記錄。理想情況下，您的來源系統將包含這些值。如果ID無法使用，請考慮串連記錄中其他欄位的值，以建立可在重新擷取時從記錄一致地重新產生的唯一值。

NOTE

以下API呼叫會 not 需要任何驗證標頭。

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"
            },
        "identityMap": {
                "Email": [
                  {
                    "id": "acme_user@gmail.com",
                    "primary": true
                  }
                ]
              },
        },
        "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": "{ORG_ID}",
        "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 以擷取時間序列資料。這可以透過向以下專案的GET請求來完成： /access/entities 端點並使用選用的查詢引數。可以使用多個引數，以&分隔。」

NOTE

如果未定義合併原則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: {ORG_ID}" \
  -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。如需詳細資訊，請閱讀監控資料擷取指南。

如需串流擷取的詳細資訊，請閱讀串流擷取概觀.

recommendation-more-help

2ee14710-6ba4-4feb-9f79-0aad73102a9a