Documentación Experience Platform Guía de acceso a datos

Visualización de datos de conjuntos de datos mediante Data Access API

Last update: Fri Dec 22 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Temas:
Data Access

Creado para:

Developer

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}

NOTE

Para obtener más información sobre las zonas protegidas en Platform, consulte la documentación general de zona protegida.

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.

Diagrama de secuencia de la funcionalidad principal de la API de acceso a datos.

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ón
GET /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}

Propiedad

Descripción

{START_TIMESTAMP}

La marca de tiempo de inicio en milisegundos (por ejemplo, 1514836799000).

{DATASET_ID}

El identificador del conjunto de datos.

{SORT_BY}

Ordena la respuesta por el valor proporcionado. Por ejemplo, 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

Propiedad

Descripción

{BATCH_ID}

Identificador de lote del lote al que intenta acceder.

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

Propiedad

Descripción

data._links.self.href

La URL para acceder a este archivo.

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}

Propiedad

Descripción

{FILE_ID}

El identificador del archivo al que desea acceder.

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

Propiedad

Descripción

{FILE_NAME}.parquet

Nombre del archivo.

_links.self.href

Dirección URL para descargar el archivo.

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

Propiedad

Descripción

data._links.self.href

Dirección URL para descargar el archivo asociado.

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}

Propiedad

Descripción

{FILE_ID}

El identificador del archivo.

{FILE_NAME}

El nombre del archivo (por ejemplo, profiles.parquet)

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 bytes
Content-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}

Propiedad

Descripción

{FILE_ID}

El identificador del archivo.

{FILE_NAME}

El nombre del archivo (por ejemplo, profiles.parquet).

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}

Propiedad

Descripción

{FILE_ID}

El identificador del archivo.

{FILE_NAME}

El nombre del archivo (por ejemplo, profiles.parquet)

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'

Propiedad

Descripción

Range: bytes=0-99

Especifica el intervalo de bytes que se va a descargar. Si no se especifica, la API descarga todo el archivo. En este ejemplo, se descargan los primeros 100 bytes.

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}

Propiedad

Descripción

{BATCH_ID}

Identificador de lote del lote al que intenta acceder.

{OFFSET}

El índice especificado para iniciar la matriz de resultados (por ejemplo, start=0)

{LIMIT}

Controla cuántos resultados se devuelven en la matriz de resultados (por ejemplo, limit=1)

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

recommendation-more-help

d71356da-cd87-452c-8a00-68926401758f