Visualización de datos de conjuntos de datos mediante Data Access API
Utilice este tutorial paso a paso para aprender a localizar, acceder y descargar datos almacenados en un conjunto de datos mediante Data Access API en Adobe Experience Platform. Este documento presenta algunas de las características únicas de la Data Access API, como paginación y descargas parciales.
Introducción
Este tutorial requiere una comprensión práctica sobre cómo crear y rellenar un conjunto de datos. Consulte la tutorial de creación de conjuntos de datos para obtener más información.
Las secciones siguientes proporcionan información adicional que necesita saber para realizar llamadas correctamente a las API de Platform.
Lectura de llamadas de API de muestra reading-sample-api-calls
Este tutorial proporciona llamadas de API de ejemplo para demostrar cómo dar formato a las solicitudes. Estas incluyen rutas, encabezados obligatorios y cargas de solicitud con el formato correcto. También se proporciona el JSON de muestra devuelto en las respuestas de la API. Para obtener información sobre las convenciones utilizadas en la documentación de las llamadas de API de ejemplo, consulte la sección sobre cómo leer llamadas de API de ejemplo en el Experience Platform guía de solución de problemas.
Recopilación de valores para los encabezados obligatorios
Para realizar llamadas a Platform API, primero debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados obligatorios en todas las llamadas de API de Experience Platform, como se muestra a continuación:
- Autorización: Portador
{ACCESS_TOKEN}
- x-api-key:
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Todos los recursos de Experience Platform están aisladas para zonas protegidas virtuales específicas. Todas las solicitudes a Platform Las API requieren un encabezado que especifique el nombre de la zona protegida en la que se realiza la operación:
- x-sandbox-name:
{SANDBOX_NAME}
Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado adicional:
- Content-Type: application/json
Diagrama de secuencia
Este tutorial sigue los pasos descritos en el diagrama de secuencia siguiente, destacando la funcionalidad principal del Data Access API.
Para recuperar información sobre lotes y archivos, utilice la variable Catalog API. Para acceder y descargar estos archivos a través de HTTP como descargas completas o parciales, según el tamaño del archivo, utilice el Data Access API.
Busque los datos
Antes de empezar a usar el Data Access API, debe identificar la ubicación de los datos a los que desea acceder. En el Catalog API, hay dos extremos que puede utilizar para examinar los metadatos de una organización y recuperar el ID de un lote o archivo al que desee acceder:
GET /batches
: Devuelve una lista de lotes bajo su organizaciónGET /dataSetFiles
: Devuelve una lista de archivos bajo su organización
Para obtener una lista completa de los extremos en la Catalog API, consulte la Referencia de API.
Recupere una lista de lotes debajo de su organización
Uso del Catalog API, puede devolver una lista de lotes debajo de su organización:
Formato de API
GET /batches
Solicitud
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}'
Respuesta
La respuesta incluye un objeto que enumera todos los lotes relacionados con la organización, y cada valor de nivel superior representa un lote. Los objetos por lotes individuales contienen los detalles de ese lote específico. La respuesta siguiente se ha minimizado para el espacio.
{
"{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}": {
...
}
}
Filtrar la lista de lotes filter-batches-list
A menudo, los filtros son necesarios para encontrar un lote concreto a fin de recuperar datos relevantes para un caso de uso determinado. Se pueden añadir parámetros a una GET /batches
solicitud para filtrar la respuesta devuelta. La solicitud siguiente devuelve todos los lotes creados después de un tiempo especificado, dentro de un conjunto de datos concreto, ordenados por el momento en que se crearon.
Formato de API
GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
{START_TIMESTAMP}
{DATASET_ID}
{SORT_BY}
desc:created
ordena los objetos por fecha de creación en orden descendente.Solicitud
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}'
Respuesta
{ "{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"
}
}
Puede encontrar una lista completa de parámetros y filtros en la Referencia de API de catálogo.
Recupere una lista de todos los archivos que pertenecen a un lote concreto
Ahora que tiene el ID del lote al que desea acceder, puede utilizar el Data Access API para obtener una lista de los archivos que pertenecen a ese lote.
Formato de API
GET /batches/{BATCH_ID}/files
{BATCH_ID}
Solicitud
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}'
Respuesta
{
"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
La respuesta contiene una matriz de datos que enumera todos los archivos del lote especificado. Se hace referencia a los archivos por su ID de archivo, que se encuentra en dataSetFileId
field.
Acceso a un archivo mediante un ID de archivo access-file-with-file-id
Una vez que tenga un ID de archivo único, puede utilizar el Data Access API para acceder a los detalles específicos sobre el archivo, incluido su nombre, tamaño en bytes y un vínculo para descargarlo.
Formato de API
GET /files/{FILE_ID}
{FILE_ID}
Solicitud
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}'
Dependiendo de si el ID de archivo apunta a un archivo individual o a un directorio, la matriz de datos devuelta puede contener una sola entrada o una lista de archivos que pertenezcan a ese directorio. Cada elemento de archivo contiene detalles como el nombre del archivo, el tamaño en bytes y un vínculo para descargar el archivo.
Caso 1: El ID de archivo apunta a un solo archivo
Respuesta
{
"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
Caso 2: El ID de archivo apunta a un directorio
Respuesta
{
"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
Esta respuesta devuelve un directorio que contiene dos archivos independientes, con ID {FILE_ID_2}
y {FILE_ID_3}
. En este caso, debe seguir la dirección URL de cada archivo para acceder al archivo.
Recuperación de los metadatos de un archivo
Puede recuperar los metadatos de un archivo realizando una solicitud al HEAD. Devuelve los encabezados de metadatos del archivo, incluido su tamaño en bytes y formato de archivo.
Formato de API
HEAD /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Solicitud
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}'
Respuesta
Los encabezados de respuesta contienen los metadatos del archivo consultado, que incluyen:
Content-Length
: indica el tamaño de la carga útil en bytesContent-Type
: indica el tipo de archivo.
Acceder al contenido de un archivo
También puede acceder al contenido de un archivo mediante la variable Data Access API.
Formato de API
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Solicitud
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}'
Respuesta
Una respuesta correcta devuelve el contenido del archivo.
Descargar el contenido parcial de un archivo download-partial-file-contents
Para descargar un intervalo específico de bytes de un archivo, especifique un encabezado de intervalo durante una GET /files/{FILE_ID}
solicitud a la Data Access API. Si no se especifica el intervalo, la API descarga todo el archivo de forma predeterminada.
El ejemplo del HEAD en sección anterior proporciona el tamaño de un archivo específico en bytes.
Formato de API
GET /files/{FILE_ID}?path={FILE_NAME}
{FILE_ID}
{FILE_NAME}
Solicitud
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
Respuesta
El cuerpo de respuesta incluye los primeros 100 bytes del archivo (tal como especifica el encabezado "Rango" en la solicitud) junto con el estado HTTP 206 (Contenido parcial). La respuesta también incluye los siguientes encabezados:
- Content-Length: 100 (el número de bytes devueltos)
- Content-type: application/parquet (se ha solicitado un archivo Parquet; por lo tanto, el tipo de contenido de respuesta es
parquet
) - Content-Range: bytes 0-99/249058 (el intervalo solicitado (0-99) del número total de bytes (249058))
Configuración de paginación de respuesta API configure-response-pagination
Respuestas dentro de Data Access Las API están paginadas. De forma predeterminada, el número máximo de entradas por página es 100. Puede modificar el comportamiento predeterminado con los parámetros de paginación.
limit
: Puede especificar el número de entradas por página según sus necesidades utilizando el parámetro "limit".start
: el desplazamiento se puede establecer mediante el parámetro de consulta "inicio".&
: Puede utilizar un signo & para combinar varios parámetros en una sola llamada.
Formato de 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}
Solicitud
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}'
Respuesta:
La respuesta contiene un "data"
matriz con un solo elemento, según lo especificado por el parámetro de solicitud limit=1
. Este elemento es un objeto que contiene los detalles del primer archivo disponible, tal como especifica el start=0
en la solicitud (recuerde que en la numeración basada en cero, el primer elemento es "0").
El _links.next.href
contiene el vínculo a la siguiente página de respuestas, donde puede ver que la variable start
el parámetro ha avanzado a 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
}
}
}