使用API创建流连接

流服务用于收集和集中来自Adobe Experience Platform内不同来源的客户数据。 该服务提供用户界面和RESTful API,所有受支持的源都可从中连接。

本教程使用Flow Service API指导您使用流服务API创建流连接的步骤。

入门指南

本指南要求对Adobe Experience Platform的以下组件有充分的了解:

以下各节提供了成功调用流化Ingestion API所需了解的其他信息。

读取示例API调用

本指南提供示例API调用,以演示如何设置请求的格式。 这包括路径、必需的标头和格式正确的请求负载。 还提供API响应中返回的示例JSON。 有关示例API调用文档中使用的约定的信息,请参阅Experience Platform疑难解答指南中关于如何读取示例API调用](…/…/…/…/…/landing/troubleshooting.md#how-do-i-format-an-api-request)的部分。[

收集所需标题的值

要调用Platform API,您必须首先完成身份验证教程。 完成身份验证教程后,将为所有Experience Platform API调用中每个所需标头提供值,如下所示:

  • 授权:承载{ACCESS_TOKEN}
  • x-api-key:{API_KEY}
  • x-gw-ims-org-id:{IMS_ORG}

Experience Platform中的所有资源(包括属于Flow Service的资源)都隔离到特定虚拟沙箱。 对Platform API的所有请求都需要一个头,该头指定操作将在中执行的沙箱的名称:

  • x-sandbox-name:{SANDBOX_NAME}
注意

有关Platform中沙箱的详细信息,请参阅沙箱概述文档

所有包含有效负荷(POST、PUT、PATCH)的请求都需要额外的标头:

  • 内容类型:application/json

创建连接

连接指定源并包含使流与流摄取API兼容所需的信息。 创建连接时,您可以选择创建未验证和已验证的连接。

未验证连接

非身份验证连接是您在希望将数据流到平台时可以创建的标准流连接。

API格式

POST /flowservice/connections

请求

要创建流连接,必须在POST请求中提供提供者ID和连接规范ID。 提供程序ID为521eee4d-8cbe-4906-bb48-fb6bd4450033,连接规范ID为bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb

curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
     "name": "Sample streaming connection",
     "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
     "description": "Sample description",
     "connectionSpec": {
         "id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
         "version": "1.0"
     },
     "auth": {
         "specName": "Streaming Connection",
         "params": {
             "sourceId": "Sample connection",
             "dataType": "xdm",
             "name": "Sample connection"
         }
     }
 }
属性 描述
auth.params.sourceId 要创建的流连接的ID。
auth.params.dataType 流连接的数据类型。 此值必须为xdm
auth.params.name 要创建的流连接的名称。
connectionSpec.id 用于流连接的连接规范id

响应

成功的响应返回HTTP状态201,其中包含新创建的连接的详细信息,包括其唯一标识符(id)。

{
    "id": "77a05521-91d6-451c-a055-2191d6851c34",
    "etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
属性 描述
id 您新创建的连接的id。 此处将称为{CONNECTION_ID}
etag 分配给连接的标识符,指定连接的修订版本。

已验证的连接

需要区分来自可信和不可信来源的记录时,应使用经过身份验证的连接。 希望使用个人身份信息(PII)发送信息的用户应在将信息流到平台时创建经过身份验证的连接。

API格式

POST /flowservice/connections

请求

要创建流连接,必须在POST请求中提供提供者ID和连接规范ID。 提供程序ID为521eee4d-8cbe-4906-bb48-fb6bd4450033,连接规范ID为bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb

curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
     "name": "Sample streaming connection",
     "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
     "description": "Sample description",
     "connectionSpec": {
         "id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
         "version": "1.0"
     },
     "auth": {
         "specName": "Streaming Connection",
         "params": {
             "sourceId": "Sample connection",
             "dataType": "xdm",
             "name": "Sample connection",
             "authenticationRequired": true
         }
     }
 }
属性 描述
auth.params.sourceId 要创建的流连接的ID。
auth.params.dataType 流连接的数据类型。 此值必须为xdm
auth.params.name 要创建的流连接的名称。
auth.params.authenticationRequired 指定已创建的流连接的参数
connectionSpec.id 用于流连接的连接规范id

响应

成功的响应返回HTTP状态201,其中包含新创建的连接的详细信息,包括其唯一标识符(id)。

{
    "id": "77a05521-91d6-451c-a055-2191d6851c34",
    "etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
属性 描述
id 您新创建的连接的id。 此处将称为{CONNECTION_ID}
etag 分配给连接的标识符,指定连接的修订版本。

获取流端点URL

创建连接后,您现在可以检索流端点URL。

API格式

GET /flowservice/connections/{CONNECTION_ID}
参数 描述
{CONNECTION_ID} 您之前创建的连接的id值。

请求

curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

成功的响应返回HTTP状态200,其中包含有关所请求连接的详细信息。 流端点URL是使用连接自动创建的,可使用inletUrl值进行检索。

{
    "items": [
        {
            "createdAt": 1583971856947,
            "updatedAt": 1583971856947,
            "createdBy": "{API_KEY}",
            "updatedBy": "{API_KEY}",
            "createdClient": "{USER_ID}",
            "updatedClient": "{USER_ID}",
            "id": "77a05521-91d6-451c-a055-2191d6851c34",
            "name": "Another new sample connection (Experience Event)",
            "description": "Sample description",
            "connectionSpec": {
                "id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
                "version": "1.0"
            },
            "state": "enabled",
            "auth": {
                "specName": "Streaming Connection",
                "params": {
                    "sourceId": "Sample connection (ExperienceEvent)",
                    "inletUrl": "https://dcs.adobedc.net/collection/a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
                    "inletId": "a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
                    "dataType": "xdm",
                    "name": "Sample connection (ExperienceEvent)"
                }
            },
            "version": "\"56008aee-0000-0200-0000-5e697e150000\"",
            "etag": "\"56008aee-0000-0200-0000-5e697e150000\""
        }
    ]
}

后续步骤

通过本教程,您创建了一个流式HTTP连接,使您能够使用流式端点将数据引入平台。 有关在UI中创建流连接的说明,请阅读创建流连接教程

要了解如何将数据流化到平台,请阅读关于流式时间系列数据的教程或关于流式记录数据的教程。

附录

本节提供有关使用API创建流连接的补充信息。

向经过身份验证的流连接发送消息

如果流连接启用了身份验证,则客户端需要向其请求中添加Authorization头。

如果Authorization标头不存在,或发送了无效/过期的访问令牌,则将返回HTTP 401未授权响应,响应类似如下:

响应

{
    "type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
    "status": "401",
    "title": "Authorization",
    "report": {
        "message": "[id] Ims service token is empty"
    }
}

在此页面上

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
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