使用流服务API将Data Landing Zone连接到Adobe Experience Platform

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：

创建对象：

undefined

IMPORTANT

此页面特定于Experience Platform中的Data Landing Zone 源连接器。有关连接到Data Landing Zone 目标连接器的信息，请参阅Data Landing Zone 目标文档页面。

Data Landing Zone是一种安全的基于云的文件存储工具，可将文件导入Adobe Experience Platform。数据会在七天后自动从Data Landing Zone中删除。

本教程将指导您完成有关如何使用Flow Service API创建Data Landing Zone源连接的步骤。本教程还提供了有关如何检索Data Landing Zone以及查看和刷新凭据的说明。

快速入门

本指南要求您对Experience Platform的以下组件有一定的了解：

源：Experience Platform允许从各种源摄取数据，同时允许您使用Platform服务来构建、标记和增强传入数据。
沙盒：Experience Platform提供了将单个Platform实例划分为多个单独的虚拟环境的虚拟沙盒，以帮助开发和改进数字体验应用程序。

以下部分提供使用Flow Service API成功创建Data Landing Zone源连接所需了解的其他信息。

本教程还要求您阅读Platform API快速入门指南，了解如何对Platform API进行身份验证并解释文档中提供的示例调用。

检索可用的登陆区域

使用API访问Data Landing Zone的第一步是向Connectors API的/landingzone端点发出GET请求，同时将type=user_drop_zone作为请求标头的一部分提供。

API格式

GET /data/foundation/connectors/landingzone?type=user_drop_zone

标头

描述

user_drop_zone

user_drop_zone类型允许API将登陆区域容器与您可用的其他类型容器区分开来。

请求

以下请求将检索现有的登陆区域。

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
  -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}' \
  -H 'Content-Type: application/json'

响应

以下响应返回有关登陆区域的信息，包括其对应的containerName和containerTTL。

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}

属性

描述

containerName

您检索到的登陆区域的名称。

containerTTL

适用于登陆区域内数据的过期时间（以天为单位）。七天后，会删除给定登陆区域内的任何区域。

检索Data Landing Zone凭据

要检索Data Landing Zone的凭据，请向Connectors API的/credentials端点发出GET请求。

API格式

GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone

请求

以下请求示例检索现有登陆区域的凭据。

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
  -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}' \
  -H 'Content-Type: application/json' \

响应

以下响应返回数据登录区域的凭据信息，包括当前的SASToken、SASUri、storageAccountName和到期日期。

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "expiryDate": "2024-01-06"
}

属性

描述

containerName

您的登陆区域的名称。

SASToken

登陆区域的共享访问签名令牌。此字符串包含授权请求所需的所有信息。

SASUri

登陆区域的共享访问签名URI。此字符串是您要进行身份验证的登陆区域的URI及其对应的SAS令牌的组合，

expiryDate

SAS令牌的过期日期。您必须在到期日期之前刷新您的令牌，才能继续在您的应用程序中使用它来将数据上载到数据登陆区。如果您未在规定的到期日期之前手动刷新令牌，则会在执行GET凭据调用时自动刷新并提供新令牌。

更新Data Landing Zone凭据

您可以通过向Connectors API的/credentials端点发出POST请求来更新SASToken。

API格式

POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh

标头

描述

user_drop_zone

user_drop_zone类型允许API将登陆区域容器与您可用的其他类型容器区分开来。

refresh

refresh操作允许您重置登陆区域凭据并自动生成新的SASToken。

请求

以下请求将更新您的登陆区域凭据。

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
  -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}' \
  -H 'Content-Type: application/json' \

响应

以下响应返回您的SASToken和SASUri的更新值。

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "expiryDate": "2024-01-06"
}

探索登陆区域文件结构和内容

您可以通过向Flow Service API的connectionSpecs端点发出GET请求来探索登陆区域的文件结构和内容。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root

参数

描述

{CONNECTION_SPEC_ID}

对应于Data Landing Zone的连接规范ID。此固定ID为： 26f526f2-58f4-4712-961d-e41bf1ccc0e8。

请求

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
    -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}'

响应

成功的响应将返回在查询的目录中找到的文件和文件夹数组。请记下要上传的文件的path属性，因为您需要在下一步中提供该属性以检查其结构。

[
    {
        "type": "file",
        "name": "account.csv",
        "path": "dlz-user-container/account.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "file",
        "name": "data8.csv",
        "path": "dlz-user-container/data8.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "folder",
        "name": "userdata1",
        "path": "dlz-user-container/userdata1/",
        "canPreview": false,
        "canFetchSchema": false
    }
]

预览登陆区域文件结构和内容

要在登陆区域中检查文件的结构，请在提供文件路径并键入作为查询参数的同时执行GET请求。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}

参数

描述

示例

{CONNECTION_SPEC_ID}

对应于Data Landing Zone的连接规范ID。此固定ID为： 26f526f2-58f4-4712-961d-e41bf1ccc0e8。

{OBJECT_TYPE}

要访问的对象的类型。

file

{OBJECT}

要访问的对象的路径和名称。

dlz-user-container/data8.csv

{FILE_TYPE}

文件的类型。

delimited
json
parquet

{PREVIEW}

一个布尔值，定义是否支持文件预览。

true
false

请求

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
    -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}'

响应

成功的响应将返回查询文件的结构，包括文件名和数据类型。

{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "Id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "FirstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "LastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Phone",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "Email": "rsmith@abc.com",
            "FirstName": "Richard",
            "Phone": "111111111",
            "Id": "12345",
            "LastName": "Smith"
        },
        {
            "Email": "morgan@bac.com",
            "FirstName": "Morgan",
            "Phone": "22222222222",
            "Id": "67890",
            "LastName": "Hart"
        }
    ]
}

使用`determineProperties`自动检测Data Landing Zone的文件属性信息

在进行GET调用以探索源的内容和结构时，可以使用determineProperties参数自动检测Data Landing Zone文件内容的属性信息。

`determineProperties`用例

下表概述了在使用determineProperties查询参数或手动提供文件信息时可能会遇到的不同情况。

determineProperties

queryParams

响应

True

不适用

如果将determineProperties作为查询参数提供，则进行文件属性检测，响应将返回新的properties键，该键包括关于文件类型、压缩类型和列分隔符的信息。

不适用

True

如果文件类型、压缩类型和列分隔符的值作为queryParams的一部分手动提供，则它们将用于生成架构，并且相同的属性作为响应的一部分返回。

True

如果同时执行这两个选项，则会返回错误。

不适用

如果两个选项均未提供，则会返回错误，因为无法获取响应的属性。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true

参数

描述

示例

determineProperties

此查询参数允许Flow Service API检测有关文件属性的信息，包括有关文件类型、压缩类型和列分隔符的信息。

true

请求

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
    -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}'

响应

成功的响应将返回查询文件的结构，包括文件名和数据类型，以及包含有关fileType、compressionType和columnDelimiter信息的properties键。

单击我

code language-json

code language-json
{ "properties": { "fileType": "delimited", "compressionType": "tarGzip", "columnDelimiter": "~" }, "format": "flat", "schema": { "columns": [ { "name": "id", "type": "string", "xdm": { "type": "string" } }, { "name": "firstName", "type": "string", "xdm": { "type": "string" } }, { "name": "lastName", "type": "string", "xdm": { "type": "string" } }, { "name": "email", "type": "string", "xdm": { "type": "string" } }, { "name": "birthday", "type": "string", "xdm": { "type": "string" } } ] }, "data": [ { "birthday": "1313-0505-19731973", "firstName": "Yvonne", "lastName": "Thilda", "id": "100", "email": "Yvonne.Thilda@yopmail.com" }, { "birthday": "1515-1212-19731973", "firstName": "Mary", "lastName": "Pillsbury", "id": "101", "email": "Mary.Pillsbury@yopmail.com" }, { "birthday": "0505-1010-19751975", "firstName": "Corene", "lastName": "Joeann", "id": "102", "email": "Corene.Joeann@yopmail.com" }, { "birthday": "2727-0303-19901990", "firstName": "Dari", "lastName": "Greenwald", "id": "103", "email": "Dari.Greenwald@yopmail.com" }, { "birthday": "1717-0404-19651965", "firstName": "Lucy", "lastName": "Magdalen", "id": "199", "email": "Lucy.Magdalen@yopmail.com" } ] }

{
    "properties": {
        "fileType": "delimited",
        "compressionType": "tarGzip",
        "columnDelimiter": "~"
    },
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "firstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "lastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "birthday",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "birthday": "1313-0505-19731973",
            "firstName": "Yvonne",
            "lastName": "Thilda",
            "id": "100",
            "email": "Yvonne.Thilda@yopmail.com"
        },
        {
            "birthday": "1515-1212-19731973",
            "firstName": "Mary",
            "lastName": "Pillsbury",
            "id": "101",
            "email": "Mary.Pillsbury@yopmail.com"
        },
        {
            "birthday": "0505-1010-19751975",
            "firstName": "Corene",
            "lastName": "Joeann",
            "id": "102",
            "email": "Corene.Joeann@yopmail.com"
        },
        {
            "birthday": "2727-0303-19901990",
            "firstName": "Dari",
            "lastName": "Greenwald",
            "id": "103",
            "email": "Dari.Greenwald@yopmail.com"
        },
        {
            "birthday": "1717-0404-19651965",
            "firstName": "Lucy",
            "lastName": "Magdalen",
            "id": "199",
            "email": "Lucy.Magdalen@yopmail.com"
        }
    ]
}

属性

描述

properties.fileType

查询文件的相应文件类型。支持的文件类型为： delimited、json和parquet。

properties.compressionType

用于查询文件的相应压缩类型。支持的压缩类型包括：

bzip2
gzip
zipDeflate
tarGzip
tar

properties.columnDelimiter

用于查询文件的相应列分隔符。任何单个字符值都是允许的列分隔符。默认值为逗号(,)。

创建源连接

源连接创建和管理与摄取数据的外部源的连接。源连接由数据源、数据格式和创建数据流所需的源连接ID等信息组成。源连接实例特定于租户和组织。

要创建源连接，请向Flow Service API的/sourceConnections端点发出POST请求。

API格式

POST /sourceConnections

请求

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
    -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}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Data Landing Zone source connection",
        "data": {
            "format": "delimited"
        },
        "params": {
            "path": "dlz-user-container/data8.csv"
        },
        "connectionSpec": {
            "id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
            "version": "1.0"
        }
    }'

属性

描述

name

Data Landing Zone源连接的名称。

data.format

您要带到Platform的数据的格式。

params.path

要带到Platform的文件的路径。

connectionSpec.id

对应于Data Landing Zone的连接规范ID。此固定ID为： 26f526f2-58f4-4712-961d-e41bf1ccc0e8。

响应

成功的响应返回新创建的源连接的唯一标识符(id)。在下一个教程中，创建数据流时需要此ID。

{
    "id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
    "etag": "\"1400d460-0000-0200-0000-613be3520000\""
}

后续步骤

通过完成本教程，您已检索到Data Landing Zone凭据，探索了其文件结构以查找要带到Platform的文件，并创建了源连接以开始将您的数据带到Platform。您现在可以继续下一教程，其中您将学习如何创建数据流以使用 Flow Service API将云存储数据引入平台。

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089

使用流服务API将Data Landing Zone连接到Adobe Experience Platform

快速入门

检索可用的登陆区域

检索Data Landing Zone凭据

更新Data Landing Zone凭据

探索登陆区域文件结构和内容

预览登陆区域文件结构和内容

使用determineProperties自动检测Data Landing Zone的文件属性信息

determineProperties用例

创建源连接

后续步骤

使用`determineProperties`自动检测Data Landing Zone的文件属性信息

`determineProperties`用例