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

IMPORTANT
此页面特定于 Data Landing Zone Experience Platform中的连接器。 有关连接到 Data Landing Zone 目标 连接器,请参阅 Data Landing Zone 目标文档页面.

Data Landing Zone 是一个安全、基于云的文件存储工具,可将文件导入Adobe Experience Platform。 数据将自动从 Data Landing Zone 七天之后。

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

快速入门

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

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

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

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

检索可用的登陆区域

使用API访问的第一步 Data Landing Zone GET就是向 /landingzone 的端点 Connectors API,同时提供 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'

响应

以下响应返回有关登陆区域的信息,包括相应的登陆区域 containerNamecontainerTTL.

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}
属性
描述
containerName
您检索到的登陆区域的名称。
containerTTL
适用于登陆区域内数据的过期时间(以天为单位)。 七天后,会删除给定登陆区域内的任何区域。

Retrieve Data Landing Zone 凭据

要检索凭据,请执行以下操作 Data Landing ZoneGET ,向 /credentials 的端点 Connectors API。

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' \

响应

以下响应将返回您的数据登陆区域的凭据信息,包括您当前的 SASTokenSASUristorageAccountName和到期日期。

{
    "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 凭据

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

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' \

响应

以下响应会返回以下项的更新值: SASTokenSASUri.

{
    "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"
}

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

您可以向以下网站发出GET请求,以浏览登陆区域的文件结构和内容: connectionSpecs 的端点 Flow Service API。

API格式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
参数
描述
{CONNECTION_SPEC_ID}
与对应的连接规范ID Data Landing Zone. 此固定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}
与对应的连接规范ID Data Landing Zone. 此固定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

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

determineProperties 用例

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

determineProperties
queryParams
响应
True
不适用
如果 determineProperties 提供作为查询参数,则进行文件属性检测并且响应返回新的 properties 键,其中包括有关文件类型、压缩类型和列分隔符的信息。
不适用
True
如果文件类型、压缩类型和列分隔符的值是作为的一部分手动提供的 queryParams,然后使用它们来生成架构,并且相同的属性将作为响应的一部分返回。
True
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}'

响应

成功的响应将返回查询文件的结构,包括文件名和数据类型,以及 properties 键,包含有关以下项的信息 fileTypecompressionType、和 columnDelimiter.

单击这里
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
查询文件的相应文件类型。 支持的文件类型包括: delimitedjson、和 parquet.
properties.compressionType

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

  • bzip2
  • gzip
  • zipDeflate
  • tarGzip
  • tar
properties.columnDelimiter
用于查询文件的相应列分隔符。 任何单个字符值都是允许的列分隔符。 默认值为逗号 (,).

创建源连接

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

POST要创建源连接,请向 /sourceConnections 的端点 Flow Service API。

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
与对应的连接规范ID Data Landing Zone. 此固定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