此文档提供了一个分步教程,其中涵盖如何使用Adobe Experience Platform的API查找、访问和下载数据集中存储 Data Access 的数据。 您还将介绍API的一些独特功能, Data Access 如分页和部分下载。
本教程需要学习如何创建和填充数据集。 有关详细 信息,请参阅数据集 创建教程。
以下各节提供了成功调用平台API所需了解的其他信息。
本教程提供示例API调用,以演示如何设置请求的格式。 这包括路径、必需的标头和格式正确的请求负载。 还提供API响应中返回的示例JSON。 有关示例API调用文档中使用的惯例的信息,请参阅疑难解答 指南中有关如何阅读示例API调 用 Experience Platform 一节。
要调用API,您必 Platform 须先完成身份验证 教程。 完成身份验证教程可为所有API调用中的每个所需 Experience Platform 标头提供值,如下所示:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
中的所有资源 Experience Platform 都与特定虚拟沙箱隔离。 对API的 Platform 所有请求都需要一个标头,它指定操作将在中进行的沙箱的名称:
{SANDBOX_NAME}
有关中沙箱的详细信 Platform息,请参阅 沙箱概述文档。
所有包含有效负荷(POST、PUT、PATCH)的请求都需要附加标头:
本教程遵循以下序列图中概述的步骤,重点介绍API的核心功 Data Access 能。
API Catalog 允许您检索有关批处理和文件的信息。 API Data Access 允许您通过HTTP访问和下载这些文件,作为完整或部分下载,具体取决于文件的大小。
在开始使用API之 Data Access 前,您需要先确定要访问的数据的位置。 在API Catalog 中,您可以使用两个端点来浏览组织的元数据并检索要访问的批处理或文件的ID:
GET /batches
:返回组织下的批列表GET /dataSetFiles
:返回组织下的列表文件有关API中端点的全 Catalog 面列表,请参阅 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
响应包括一个对象,该对象列表与IMS组织相关的所有批,每个顶级值代表一个批。 单个批处理对象包含该特定批处理的详细信息。 以下响应已最小化为空间。
{
"{BATCH_ID_1}": {
"imsOrg": "{IMS_ORG}",
"created": 1516640135526,
"createdClient": "{CREATED_CLIENT}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"updated": 1516640135526,
"status": "processing",
"version": "1.0.0",
"availableDates": {}
},
"{BATCH_ID_2}": {
...
}
}
过滤器通常需要查找特定批,才能检索特定用例的相关数据。 可以将参数添加到 GET /batches
请求中以过滤返回的响应。 以下请求将返回在指定时间后创建的所有批,这些批在特定数据集中按创建时间排序。
API格式
GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
属性 | 描述 |
---|---|
{START_TIMESTAMP} |
开始时间戳(以毫秒为单位)(例如,1514836799000)。 |
{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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
{ "{BATCH_ID_3}": {
"imsOrg": "{IMS_ORG}",
"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": "{IMS_ORG}",
"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: {IMS_ORG}' \
-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 |
访问此文件的URL。 |
响应包含一个列表指定批次中所有文件的数据数组。 文件由其文件ID引用,该ID位于字段 dataSetFileId
下。
获得唯一的文件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: {IMS_ORG}' \
-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 |
用于下载文件的URL。 |
案例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 |
用于下载相关文件的URL。 |
此响应返回一个包含两个单独文件(ID和)的 {FILE_ID_2}
目录 {FILE_ID_3}
。 在这种情况下,您需要按照每个文件的URL来访问该文件。
您可以通过发出HEAD请求来检索文件的元数据。 这将返回文件的元数据标题,包括其大小(以字节为单位)和文件格式。
API格式
HEAD /files/{FILE_ID}?path={FILE_NAME}
属性 | 描述 |
---|---|
{FILE_ID} |
文件的标识符。 |
{FILE_NAME} |
文件名(例如,用户档案.parke) |
请求
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
响应标头包含查询的文件的元数据,包括:
Content-Length
:指示有效负荷的大小(以字节为单位)Content-Type
:指示文件类型。您还可以使用API访问文件的内 Data Access 容。
API格式
GET /files/{FILE_ID}?path={FILE_NAME}
属性 | 描述 |
---|---|
{FILE_ID} |
文件的标识符。 |
{FILE_NAME} |
文件名(例如,用户档案.parke)。 |
请求
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
响应
成功的响应会返回文件的内容。
API允 Data Access 许下载块中的文件。 在请求从文件下载特定范围的字 GET /files/{FILE_ID}
节时,可以指定范围标头。 如果未指定范围,则默认情况下API将下载整个文件。
上一节中的HEAD 示例 ,以字节为单位给出特定文件的大小。
API格式
GET /files/{FILE_ID}?path={FILE_NAME}
属性 | 描述 |
---|---|
{FILE_ID} |
文件的标识符。 |
{FILE_NAME} |
文件名(例如,用户档案.parke) |
请求
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Range: bytes=0-99'
属性 | 描述 |
---|---|
Range: bytes=0-99 |
指定要下载的字节范围。 如果未指定,API将下载整个文件。 在此示例中,将下载前100字节。 |
响应
响应主体包括文件的前100字节(由请求中的“范围”标头指定)和HTTP状态206(部分内容)。 响应还包含以下标题:
API中的响 Data Access 应将分页。 默认情况下,每页最大条目数为100。 分页参数可用于修改默认行为。
limit
:您可以使用“limit”参数根据您的要求指定每页的条目数。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} |
用于开始结果数组的指定索引(例如,开始=0) |
{LIMIT} |
控制结果数组中返回的结果数(例如,limit=1) |
请求
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: {IMS_ORG}' \
-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
}
}
}