使用导出数据集 Flow Service API
- 已购买Real-Time CDP Prime和Ultimate软件包、Adobe Journey Optimizer或Customer Journey Analytics的客户可以使用此功能。 有关更多信息,请与您的Adobe代表联系。
本文说明了使用 Flow Service API 以导出 数据集 从Adobe Experience Platform到您的首选云存储位置,例如 Amazon S3、 SFTP位置或 Google Cloud Storage.
可用于导出的数据集 datasets-to-export
您可以导出的数据集取决于Experience Platform应用程序(Real-Time CDP、Adobe Journey Optimizer)、层(Prime或Ultimate)以及您购买的任何加载项(例如:Data Distiller)。
请参阅 UI教程页面上的表 以了解可以导出哪些数据集。
支持的目标 supported-destinations
目前,您可以将数据集导出到屏幕快照中突出显示的云存储目标,如下所列。
快速入门 get-started
本指南要求您对 Adobe Experience Platform 的以下组件有一定了解:
- Experience Platform datasets:所有成功摄取到Adobe Experience Platform的数据将保留在 Data Lake 作为数据集。 数据集是用于数据集合的存储和管理结构,通常是表格,其中包含架构(列)和字段(行)。数据集还包含描述其存储的数据的各方面特性的元数据。
- Sandboxes: Experience Platform 提供对单个文件夹进行分区的虚拟沙盒 Platform 将实例安装到单独的虚拟环境中,以帮助开发和改进数字体验应用程序。
以下部分提供了要将数据集导出到Platform中的云存储目标必须了解的其他信息。
所需权限 permissions
要导出数据集,您需要 查看目标, 查看数据集、和 管理和激活数据集目标 访问控制权限. 阅读 访问控制概述 或与产品管理员联系以获取所需的权限。
要确保您具有导出数据集的必要权限并且目标支持导出数据集,请浏览目标目录。 如果目标具有 激活 或 导出数据集 则您具有相应的权限。
正在读取示例 API 调用 reading-sample-api-calls
本教程提供了示例API调用来演示如何格式化请求。 这些包括路径、必需的标头和格式正确的请求负载。还提供了在 API 响应中返回的示例 JSON。有关示例 API 调用的文档中使用的惯例信息,请参阅 故障排除指南中的如何读取示例 API 调用Experience Platform。
收集必需标题和可选标题的值 gather-values-headers
为了调用 Platform API,您必须先完成 Experience Platform身份验证教程. 完成身份验证教程会提供所有 Experience Platform API 调用中每个所需标头的值,如下所示:
- 授权:持有者
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
中的资源 Experience Platform 可以隔离到特定的虚拟沙箱。 在请求中 Platform API中,您可以指定将在其中执行操作的沙盒的名称和ID。 这些是可选参数。
- x-sandbox-name:
{SANDBOX_NAME}
所有包含有效负载(POST、PUT、PATCH)的请求都需要额外的媒体类型标头:
- Content-Type:
application/json
API参考文档 api-reference-documentation
您可以在本教程中找到所有API操作的随附参考文档。 请参阅 Flow Service - Adobe Developer网站上的目标API文档. 我们建议您并行使用此教程和API参考文档。
术语表 glossary
有关在此API教程中遇到的术语的描述,请参阅 词汇表部分 API参考文档的URL名称。
收集所需目标的连接规格和流量规格 gather-connection-spec-flow-spec
在开始导出数据集的工作流之前,请确定要将数据集导出到的目标的连接规范和流量规范ID。 请参考下表。
4fce964d-3f37-408f-9778-e597338a21ee
269ba276-16fc-47db-92b0-c1049a3c131f
6d6b59bf-fb58-4107-9064-4d246c0e5bb2
95bd8965-fc8a-4119-b9c3-944c2c2df6d2
be2c3209-53bc-47e7-ab25-145db8b873e1
17be2013-2549-41ce-96e7-a70363bec293
10440537-2a7b-4583-ac39-ed38d4b848e8
cd2fc47e-e838-4f38-a581-8fff2f99b63a
c5d93acb-ea8b-4b14-8f53-02138444ae99
585c15c4-6cbf-4126-8f87-e26bff78b657
36965a81-b1c6-401b-99f8-22508f1e6a26
354d6aad-4754-46e4-a576-1b384561c440
您需要这些ID Flow Service 实体。 您还需要参考 Connection Spec 设置特定图元,以便您能够检索 Connection Spec 从 Flow Service APIs. 请参阅下面的示例,以了解如何检索表中所有目标的连接规范:
请求
accordion | ||
---|---|---|
Retrieve connection spec 对象 Amazon S3 | ||
|
响应
accordion | ||
---|---|---|
Amazon S3 — 连接规范 | ||
|
请求
accordion | ||
---|---|---|
Retrieve connection spec 对象 Azure Blob Storage | ||
|
响应
accordion | ||
---|---|---|
Azure Blob Storage — Connection spec | ||
|
请求
accordion | ||
---|---|---|
Retrieve connection spec 对象 Azure Data Lake Gen 2(ADLS Gen2) | ||
|
响应
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) — Connection spec | ||
|
请求
accordion | ||
---|---|---|
Retrieve connection spec 对象 Data Landing Zone(DLZ) | ||
|
响应
accordion | ||
---|---|---|
Data Landing Zone(DLZ) — Connection spec | ||
|
请求
accordion | ||
---|---|---|
Retrieve connection spec 对象 Google Cloud Storage | ||
|
响应
accordion | ||
---|---|---|
Google Cloud Storage — Connection spec | ||
|
请求
accordion | ||
---|---|---|
Retrieve connection spec 对于SFTP | ||
|
响应
accordion | ||
---|---|---|
SFTP - Connection spec | ||
|
请按照以下步骤设置传送到云存储目标的数据集数据流。 对于某些步骤,不同云存储目标之间的请求和响应会有所不同。 在这些情况下,使用页面上的选项卡可检索特定于您要连接并导出数据集的目标的请求和响应。 请确保使用正确的 connection spec 和 flow spec (对于您正在配置的目标)。
检索数据集列表 retrieve-list-of-available-datasets
要检索符合激活条件的数据集列表,首先要对以下端点进行API调用。
请求
code language-shell |
---|
|
请注意,要检索符合条件的数据集,请 connection spec 请求URL中使用的ID必须是数据湖源连接规范ID, 23598e46-f560-407b-88d5-ea6207e49db0
和两个查询参数 outputField=datasets
和 outputType=activationDatasets
必须指定。 所有其他查询参数都是 目录服务API.
响应
code language-json |
---|
|
成功的响应包含符合激活条件的数据集列表。 在下一步中构建源连接时,可以使用这些数据集。
有关每个返回的数据集的各种响应参数的信息,请参阅 数据集API开发人员文档.
创建源连接 create-source-connection
在检索要导出的数据集列表后,您可以使用这些数据集ID创建源连接。
请求
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
code language-shell line-numbers data-start-1 data-line-offset-4 h-12 h-16 |
---|
|
响应
code language-json |
---|
|
成功的响应会返回ID (id
)和 etag
. 记下源连接ID,因为稍后创建数据流时会需要它。
另请记住:
- 在此步骤中创建的源连接需要链接到数据流,才能将其数据集激活到目标。 请参阅 创建数据流 部分,以了解如何将源连接链接到数据流。
- 源连接的数据集ID在创建后无法修改。 如果需要从源连接添加或删除数据集,则必须创建新的源连接,并将新源连接的ID链接到数据流。
创建(target)基本连接 create-base-connection
基本连接会将凭据安全地存储到您的目标。 根据目标类型,对该目标进行身份验证所需的凭据可能有所不同。 要查找这些验证参数,请先检索 connection spec (对于所需的目标,请参阅部分) 收集连接规格和流量规格 然后查看 authSpec
响应的。 请参考下面的选项卡 authSpec
所有受支持目标的属性。
accordion | ||
---|---|---|
Amazon S3 - Connection spec 显示 auth spec | ||
请注意中带有内联注释的高亮显示行 connection spec 下面示例,其中提供了有关在何处查找身份验证参数的更多信息, connection spec.
|
accordion | ||
---|---|---|
Azure Blob Storage - Connection spec 显示 auth spec | ||
请注意中带有内联注释的高亮显示行 connection spec 下面示例,其中提供了有关在何处查找身份验证参数的更多信息, connection spec.
|
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) - Connection spec 显示 auth spec | ||
请注意中带有内联注释的高亮显示行 connection spec 下面示例,其中提供了有关在何处查找身份验证参数的更多信息, connection spec.
|
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone(DLZ) - Connection spec 显示 auth spec | |||||
|
accordion | ||
---|---|---|
Google Cloud Storage - Connection spec 显示 auth spec | ||
请注意中带有内联注释的高亮显示行 connection spec 下面示例,其中提供了有关在何处查找身份验证参数的更多信息, connection spec.
|
accordion | |||||
---|---|---|---|---|---|
SFTP - Connection spec 显示 auth spec | |||||
请注意中带有内联注释的高亮显示行 connection spec 下面示例,其中提供了有关在何处查找身份验证参数的更多信息, connection spec.
|
使用身份验证规范中指定的属性(即 authSpec
(从响应中)可以使用特定于每种目标类型的所需凭据创建基本连接,如下面的示例所示:
请求
accordion | |||||
---|---|---|---|---|---|
Amazon S3 — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Amazon S3 基本连接响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Azure Blob Storage — 基本连接响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) — 基本连接响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone(DLZ) — 基本连接请求 | |||||
|
响应
accordion | ||
---|---|---|
Data Landing Zone — 基本连接响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Google Cloud Storage — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Google Cloud Storage — 基本连接响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
包含密码的SFTP — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
accordion | |||||
---|---|---|---|---|---|
使用SSH密钥的SFTP — 基本连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
SFTP — 基本连接响应 | ||
|
记下响应中的连接ID。 创建目标连接时,此ID将在下一步中是必需的。
创建目标连接 create-target-connection
接下来,您需要创建一个目标连接,用于存储数据集的导出参数。 导出参数包括位置、文件格式、压缩和其他详细信息。 请参阅 targetSpec
目标的连接规范中提供的属性,用于了解每个目标类型支持的属性。 请参考下面的选项卡 targetSpec
所有受支持目标的属性。
accordion | ||
---|---|---|
Amazon S3 - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
accordion | ||
---|---|---|
Azure Blob Storage - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
accordion | ||
---|---|---|
Azure Data Lake Gen 2(ADLS Gen2) - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
accordion | ||
---|---|---|
Data Landing Zone(DLZ) - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
accordion | ||
---|---|---|
Google Cloud Storage - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
accordion | ||
---|---|---|
SFTP - Connection spec 显示目标连接参数 | ||
请注意中带有内联注释的高亮显示行 connection spec 下面的示例,其中提供了有关在何处查找 target spec 连接规范中的参数。 您还可以在以下示例中看到以下目标参数 非 适用于数据集导出目标。
|
通过使用上述规范,您可以构建特定于所需云存储目标的目标连接请求,如下面的选项卡所示。
请求
accordion | |||||
---|---|---|---|---|---|
Amazon S3 - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
Google Cloud Storage - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
请求
accordion | |||||
---|---|---|---|---|---|
SFTP - Target连接请求 | |||||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
Target连接 — 响应 | ||
|
记下响应中的Target连接ID。 创建数据流以导出数据集时,在下一步中需要此ID。
创建数据流 create-dataflow
目标配置的最后一步是设置数据流。 数据流将以前创建的实体连接在一起,还提供了用于配置数据集导出计划的选项。 要创建数据流,请根据所需的云存储目标使用以下有效负载,并替换之前步骤中的实体ID。
请求
accordion | ||
---|---|---|
创建数据集数据流到 Amazon S3 目标 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
请求
accordion | ||
---|---|---|
创建数据集数据流到 Azure Blob Storage 目标 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
请求
accordion | ||
---|---|---|
创建数据集数据流到 Azure Data Lake Gen 2(ADLS Gen2) 目标 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
请求
accordion | ||
---|---|---|
创建数据集数据流到 Data Landing Zone 目标 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
请求
accordion | ||
---|---|---|
创建数据集数据流到 Google Cloud Storage 目标 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
请求
accordion | ||
---|---|---|
创建到SFTP目标的数据集数据流 — 请求 | ||
请注意请求示例中带有内联注释的高亮显示行,这些行提供了更多信息。 将请求复制粘贴到您选择的终端时,删除请求中的内联注释。
|
响应
accordion | ||
---|---|---|
创建数据流 — 响应 | ||
|
记下响应中的数据流ID。 检索数据流运行时在下一步中需要此ID来验证成功的日期集导出。
获取数据流运行 get-dataflow-runs
要检查数据流的执行,请使用数据流运行API:
请求
在检索数据流运行的请求中,在创建数据流时,将您在上一步中获取的数据流ID添加为查询参数。
code language-shell |
---|
|
响应
code language-json |
---|
|
您可以找到有关 数据流运行API返回的各种参数 API参考文档中的。
验证是否成功导出数据集 verify
导出数据集时,Experience Platform会创建 .json
或 .parquet
文件存储位置。 预计在下列情况下,将根据您提供的导出计划在您的存储位置存放新文件: 创建数据流.
Experience Platform会在您指定的存储位置创建一个文件夹结构,存放导出的数据集文件。 每次导出时都会创建一个新文件夹,其模式如下所示:
folder-name-you-provided/datasetID/exportTime=YYYYMMDDHHMM
默认文件名是随机生成的,并确保导出的文件名是唯一的。
示例数据集文件 sample-files
这些文件在存储位置中的存在是成功导出的确认。 要了解导出文件的结构形式,您可以下载示例 .parquet文件 或 .json文件.
压缩的数据集文件 compressed-dataset-files
在到步骤中 创建目标连接中,您可以选择要压缩的导出数据集文件。
请注意两种文件类型在压缩后的文件格式差异:
- 导出压缩的JSON文件时,导出的文件格式为
json.gz
- 导出压缩的parquet文件时,导出的文件格式为
gz.parquet
API错误处理 api-error-handling
本教程中的API端点遵循常规Experience PlatformAPI错误消息原则。 请参阅 API状态代码 和 请求标头错误 有关解释错误响应的更多信息,请参阅平台故障排除指南。
后续步骤 next-steps
通过学习本教程,您已成功将Platform连接到其中一个首选批量云存储目标,并将数据流设置到相应的目标以导出数据集。 有关更多详细信息,请参阅以下页面,例如如何使用流服务API编辑现有数据流: