使用流摄取API流式传输时间序列数据

本教程将帮助您开始使用流式摄取API，它是Adobe Experience Platform Data Ingestion Service API的一部分。

入门指南

本教程需要对各种Adobe Experience Platform服务具备工作知识。 在开始本教程之前，请查阅以下服务的文档：

  • Experience Data Model (XDM):用于组织体验数 Platform 据的标准化框架。
  • Real-time Customer Profile:根据来自多个来源的汇总数据实时提供统一的消费者用户档案。
  • 模式 Registry开发人员指南:全面的指南，涵盖API的每个可用端 Schema Registry 点以及如何向它们发出调用。这包括了解您的{TENANT_ID}（在本教程的调用中显示），以及了解如何创建模式（用于创建用于摄取的数据集）。

此外，本教程要求您已经创建了流连接。 有关创建流连接的详细信息，请阅读创建流连接教程。

以下各节提供了成功调用流化Ingestion 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

根据XDM ExperienceEvent类编写模式

要创建模式集，您首先需要创建一个实现XDM ExperienceEvent类的新数据集。 有关如何创建模式的详细信息，请阅读模式注册表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属性，因为创建数据集时将同时使用这两个属性。

为模式设置主标识描述符

然后，将标识描述符添加到上面创建的模式，使用工作电子邮件地址属性作为主标识符。 这样做将导致两处更改：

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

​身份命名空间码

请确保代码有效 — 上例使用“email”，这是标准身份命名空间。 在Identity Service FAQ中可以找到其他常用的标准标识命名空间。

如果要创建自定义命名空间，请按照标识命名空间概述中概述的步骤操作。

响应

成功的响应返回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和一个数组，其中包含格式为@/dataSets/{DATASET_ID}的新创建数据集的ID。

[
    "@/dataSets/5e72608b10f6e318ad2dee0f"
]

创建流连接

在创建模式和数据集后，您需要创建流连接以收集数据。

有关创建流连接的详细信息，请阅读创建流连接教程。

将时间序列数据收录到流连接

创建数据集、流连接和数据流后，您可以收录XDM格式的JSON记录，以在Platform内收录时间序列数据。

API格式

POST /collection/{CONNECTION_ID}?synchronousValidation=true
参数 描述
{CONNECTION_ID} 新创建的流连接的id值。
synchronousValidation 用于开发目的的可选查询参数。 如果设置为true，则可用于立即反馈，以确定请求是否成功发送。 默认情况下，此值设置为false。

请求

可以使用或不使用源名称将时间序列数据引入流连接。

下面的示例请求将缺少源名称的时间序列数据引入平台。 如果数据缺少源名称，它将从流连接定义添加源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}?synchronousValidation=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,
    "synchronousValidation": {
        "status": "pass"
    }
}
属性 描述
{CONNECTION_ID} 先前创建的流连接的inletId。
xactionId 您刚刚发送的记录在服务器端生成的唯一标识符。 此ID可帮助Adobe在各种系统和调试过程中跟踪此记录的生命周期。
receivedTimeMs:显示接收请求的时间的时间戳（以毫秒为单位）。
synchronousValidation.status 由于添加了查询参数synchronousValidation=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开始监视所摄数据。 有关详细信息，请阅读监视数据摄取指南。

有关流摄取的详细信息，请阅读流摄取概述。

On this page

Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now