查看数据集数据,使用 Data Access API
使用本分步教程了解如何使用查找、访问和下载存储在数据集中的数据。 Data Access Adobe Experience Platform中的API。 本文档介绍 Data Access API,例如分页和部分下载。
快速入门
本教程需要对如何创建和填充数据集有一定的了解。 请参阅 数据集创建教程 以了解更多信息。
以下部分提供了成功调用Platform API时需要了解的其他信息。
正在读取示例 API 调用 reading-sample-api-calls
本教程提供了示例API调用来演示如何格式化请求。 这些包括路径、必需的标头和格式正确的请求负载。还提供了在 API 响应中返回的示例 JSON。有关文档中用于示例API调用的惯例的信息,请参阅 如何读取示例API调用 在 Experience Platform 疑难解答指南。
收集所需标头的值
致电 Platform API,您必须先完成 身份验证教程. 完成身份验证教程会提供所有 Experience Platform API 调用中每个所需标头的值,如下所示:
- 授权:持有者
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
中的所有资源 Experience Platform 被隔离到特定的虚拟沙盒中。 所有请求 Platform API需要一个标头,该标头应指定执行操作的沙盒的名称:
- x-sandbox-name:
{SANDBOX_NAME}
包含负载 (POST、PUT、PATCH) 的所有请求都需要额外的标头:
- Content-Type: application/json
序列图
本教程将遵循以下顺序图中列出的步骤,其中重点介绍了 Data Access API。
要检索有关批次和文件的信息,请使用 Catalog API。 要通过HTTP访问和下载这些文件,或者完全下载,或者部分下载,具体取决于文件的大小,请使用 Data Access API。
查找数据
在开始使用 Data Access API中,您必须标识要访问的数据的位置。 在 Catalog API时,可以使用两个端点浏览组织的元数据并检索要访问的批次或文件的ID:
GET /batches
:返回组织下的批次列表GET /dataSetFiles
:返回组织下的文件列表
要查看 Catalog API,请参阅 API参考.
检索组织内的批次列表
使用 Catalog API中,您可以返回组织内的批次列表:
API格式
GET /batches
请求
curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches/' \
-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}'
响应
响应包括一个对象,该对象列出与组织相关的所有批次,每个顶级值表示一个批次。 单个批次对象包含该特定批次的详细信息。 下面的响应已最小化,占用空间。
{
"{BATCH_ID_1}": {
"imsOrg": "{ORG_ID}",
"created": 1516640135526,
"createdClient": "{CREATED_CLIENT}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1516640135526,
"status": "processing",
"version": "1.0.0",
"availableDates": {}
},
"{BATCH_ID_2}": {
...
}
}
筛选批次列表 filter-batches-list
通常,需要过滤器来查找特定批次,以检索特定用例的相关数据。 可以将参数添加到 GET /batches
请求过滤返回的响应。 以下请求返回指定时间后在特定数据集中创建的所有批次,按其创建时间排序。
API格式
GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
{START_TIMESTAMP}
{DATASET_ID}
{SORT_BY}
desc:created
按创建日期降序排列对象。请求
curl -X GET 'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1521053542579&dataSet=5cd9146b21dae914b71f654f&orderBy=desc:created' \
-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}'
响应
{ "{BATCH_ID_3}": {
"imsOrg": "{ORG_ID}",
"relatedObjects": [
{
"id": "5c01a91863540f14cd3d0439",
"type": "dataSet"
},
{
"id": "00998255b4a148a2bfd4804c2f327324",
"type": "batch"
}
],
"status": "success",
"metrics": {
"recordsFailed": 0,
"recordsWritten": 2,
"startTime": 1550791835809,
"endTime": 1550791994636
},
"errors": [],
"created": 1550791457173,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1550792060301,
"version": "1.0.116"
},
"{BATCH_ID_4}": {
"imsOrg": "{ORG_ID}",
"status": "success",
"relatedObjects": [
{
"type": "batch",
"id": "00aff31a9ae84a169d69b886cc63c063"
},
{
"type": "dataSet",
"id": "5bfde8c5905c5a000082857d"
}
],
"metrics": {
"startTime": 1544571333876,
"endTime": 1544571358291,
"recordsRead": 4,
"recordsWritten": 4
},
"errors": [],
"created": 1544571077325,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1544571368776,
"version": "1.0.3"
}
}
有关参数和过滤器的完整列表,请参阅 目录API参考.
检索属于特定批次的所有文件的列表
现在,您已获得要访问的批次的ID,可以使用 Data Access 用于获取属于该批次的文件列表的API。
API格式
GET /batches/{BATCH_ID}/files
{BATCH_ID}
请求
curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c6f332168966814cd81d3d3/files' \
-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}'
响应
{
"data": [
{
"dataSetFileId": "8dcedb36-1cb2-4496-9a38-7b2041114b56-1",
"dataSetViewId": "5cc6a9b60d4a5914b7940a7f",
"version": "1.0.0",
"created": "1558522305708",
"updated": "1558522305708",
"isValid": false,
"_links": {
"self": {
"href": "https://platform.adobe.io:443/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1"
}
}
}
],
"_page": {
"limit": 100,
"count": 1
}
}
}
data._links.self.href
响应包含一个数据数组,其中列出了指定批次中的所有文件。 文件的引用方式是其文件ID,该文件可在以下位置找到: dataSetFileId
字段。
使用文件ID访问文件 access-file-with-file-id
一旦您拥有了唯一的文件ID,您便可以使用 Data Access 用于访问有关文件的特定详细信息的API,包括其名称、大小(以字节为单位)和下载链接。
API格式
GET /files/{FILE_ID}
{FILE_ID}
请求
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1' \
-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}'
根据文件ID指向单个文件或目录,返回的数据阵列可能包含单个条目或属于该目录的文件列表。 每个文件元素都包含详细信息,例如文件名、字节大小以及用于下载文件的链接。
用例1:文件ID指向单个文件
响应
{
"data": [
{
"name": "{FILE_NAME}.parquet",
"length": "249058",
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}?path={FILE_NAME_1}.parquet"
}
}
}
],
"_page": {
"limit": 100,
"count": 1
}
}
{FILE_NAME}.parquet
_links.self.href
用例2:文件ID指向目录
响应
{
"data": [
{
"dataSetFileId": "{FILE_ID_2}",
"dataSetViewId": "460590b01ba38afd1",
"version": "1.0.0",
"created": "150151267347",
"updated": "150151267347",
"isValid": true,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_2}"
}
}
},
{
"dataSetFileId": "{FILE_ID_3}",
"dataSetViewId": "460590b01ba38afd1",
"version": "1.0.0",
"created": "150151267685",
"updated": "150151267685",
"isValid": true,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_3}"
}
}
}
],
"_page": {
"limit": 100,
"count": 2
}
}
data._links.self.href
此响应会返回一个包含两个单独文件(带ID)的目录 {FILE_ID_2}
和 {FILE_ID_3}
. 在此方案中,必须遵循每个文件的URL才能访问该文件。
检索文件的元数据
您可以通过发出HEAD请求来检索文件的元数据。 这将返回文件的元数据标头,包括其大小(以字节和文件格式表示)。
API格式
HEAD /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
请求
curl -I 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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}'
响应
响应标头包含查询文件的元数据,包括:
Content-Length
:指示有效负载的大小(以字节为单位)Content-Type
:指示文件类型。
访问文件的内容
您还可以使用访问文件的内容 Data Access API。
API格式
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
请求
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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}'
响应
成功的响应将返回文件的内容。
下载文件的部分内容 download-partial-file-contents
要从文件下载特定范围的字节,请在以下期间指定范围标头: GET /files/{FILE_ID}
请求 Data Access API。 如果未指定范围,默认情况下,API会下载整个文件。
中的HEAD示例 上一节 提供特定文件的大小(字节)。
API格式
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
请求
curl -X GET 'https://platform.adobe.io/data/foundation/export/files/8dcedb36-1cb2-4496-9a38-7b2041114b56-1?path=profiles.parquet' \
-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 'Range: bytes=0-99'
Range: bytes=0-99
响应
响应正文包括文件的前100个字节(由请求中的“Range”标头指定)以及HTTP状态206(部分内容)。 响应还包括以下标头:
- Content-Length: 100(返回的字节数)
- Content-type: application/parquet(已请求Parquet文件,因此响应内容类型为
parquet
) - Content-Range:字节0-99/249058(请求的范围(0-99),总字节数(249058))
配置API响应分页 configure-response-pagination
内的响应 Data Access API采用分页方式。 默认情况下,每页的最大条目数为100。 您可以使用分页参数修改缺省行为。
limit
:您可以使用“limit”参数,根据自己的要求指定每页的条目数。start
:可使用“start”查询参数设置偏移。&
:您可以使用&符号在一次调用中组合多个参数。
API格式
GET /batches/{BATCH_ID}/files?start={OFFSET}
GET /batches/{BATCH_ID}/files?limit={LIMIT}
GET /batches/{BATCH_ID}/files?start={OFFSET}&limit={LIMIT}
{BATCH_ID}
{OFFSET}
{LIMIT}
请求
curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1' \
-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}'
响应:
响应包含 "data"
具有单个元素的数组,如请求参数所指定 limit=1
. 此元素是一个对象,其中包含由指定的第一个可用文件的详细信息。 start=0
参数(请记住,在从零开始的编号中,第一个元素为“0”)。
此 _links.next.href
值包含指向下一页响应的链接,您可以在该页面中看到 start
参数已提升到 start=1
.
{
"data": [
{
"dataSetFileId": "{FILE_ID_1}",
"dataSetViewId": "5a9f264c2aa0cf01da4d82fa",
"version": "1.0.0",
"created": "1521053793635",
"updated": "1521053793635",
"isValid": false,
"_links": {
"self": {
"href": "https://platform.adobe.io/data/foundation/export/files/{FILE_ID_1}"
}
}
}
],
"_page": {
"limit": 1,
"count": 6
},
"_links": {
"next": {
"href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=1&limit=1"
},
"page": {
"href": "https://platform.adobe.io/data/foundation/export/batches/5c102cac7c7ebc14cd6b098e/files?start=0&limit=1",
"templated": true
}
}
}