Visualizzare i dati del set di dati utilizzando l’API Data Access

Questo documento fornisce un'esercitazione dettagliata su come individuare, accedere e scaricare i dati archiviati all'interno di un set di dati utilizzando l' Data Access API in Adobe Experience Platform. Verranno inoltre introdotte alcune funzionalità uniche dell’ API Data Access , ad esempio il paging e i download parziali.

Introduzione

Questa esercitazione richiede una comprensione approfondita su come creare e popolare un set di dati. Per ulteriori informazioni, consulta l’ esercitazione sulla creazione di set di dati .

Le sezioni seguenti forniscono informazioni aggiuntive che dovrai conoscere per effettuare correttamente le chiamate alle API di Platform.

Lettura di chiamate API di esempio

Questa esercitazione fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richiesta formattati correttamente. Viene inoltre fornito un esempio di codice JSON restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform .

Raccogli i valori delle intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l’ esercitazione sull’autenticazione. Il completamento dell’esercitazione di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come mostrato di seguito:

  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API Platform richiedono un’intestazione che specifichi il nome della sandbox in cui avrà luogo l’operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sandbox.

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:

  • Tipo di contenuto: application/json

Diagramma della sequenza

Questa esercitazione segue i passaggi descritti nel diagramma di sequenza seguente, evidenziando le funzionalità di base dell' Data Access API.

L’ API Catalog ti consente di recuperare informazioni relative a batch e file. L’ Data Access API ti consente di accedere e scaricare questi file tramite HTTP come download completi o parziali, a seconda delle dimensioni del file.

Individuare i dati

Prima di poter iniziare a utilizzare l’ API Data Access , devi identificare la posizione dei dati a cui desideri accedere. Nell’API Catalog sono disponibili due endpoint da utilizzare per sfogliare i metadati di un’organizzazione e recuperare l’ID di un batch o di un file a cui si desidera accedere:

  • GET /batches: Restituisce un elenco di batch nell'organizzazione
  • GET /dataSetFiles: Restituisce un elenco di file nell'organizzazione

Per un elenco completo degli endpoint nell' API Catalog, fai riferimento alla Guida di riferimento API.

Recupera un elenco di batch nell’organizzazione IMS

Utilizzando l’ API Catalog, puoi restituire un elenco di batch nell’organizzazione:

Formato API

GET /batches

Richiesta

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

Risposta

La risposta include un oggetto che elenca tutti i batch relativi all’organizzazione IMS, con ogni valore di livello superiore che rappresenta un batch. I singoli oggetti batch contengono i dettagli di quel batch specifico. La risposta seguente è stata ridotta a icona per lo spazio.

{
    "{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}": {
    ...
    }
}

Filtrare l’elenco dei batch

Spesso sono necessari filtri per trovare un particolare batch al fine di recuperare i dati rilevanti per un particolare caso d’uso. È possibile aggiungere parametri a una richiesta GET /batches per filtrare la risposta restituita. La richiesta seguente restituisce tutti i batch creati dopo un determinato periodo di tempo, all’interno di un particolare set di dati, ordinati in base a quando sono stati creati.

Formato API

GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}
Proprietà Descrizione
{START_TIMESTAMP} La marca temporale iniziale in millisecondi (ad esempio, 1514836799000).
{DATASET_ID} Identificatore del set di dati.
{SORT_BY} Ordina la risposta in base al valore fornito. Ad esempio, desc:created ordina gli oggetti in base alla data di creazione in ordine decrescente.

Richiesta

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

Risposta

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

Un elenco completo dei parametri e dei filtri si trova nella sezione Riferimento API del catalogo.

Recupera un elenco di tutti i file appartenenti a un particolare batch

Ora che disponi dell’ID del batch a cui desideri accedere, puoi utilizzare l’ API Data Access per ottenere un elenco di file appartenenti a tale batch.

Formato API

GET /batches/{BATCH_ID}/files
Proprietà Descrizione
{BATCH_ID} Identificatore batch del batch a cui si sta tentando di accedere.

Richiesta

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

Risposta

{
    "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
    }
}
}
Proprietà Descrizione
data._links.self.href URL per accedere a questo file.

La risposta contiene un array di dati che elenca tutti i file all'interno del batch specificato. Ai file viene fatto riferimento dal loro ID file, che si trova nel campo dataSetFileId .

Accedere a un file utilizzando un ID file

Una volta ottenuto un ID file univoco, puoi utilizzare l’ Data Access API per accedere ai dettagli specifici sul file, tra cui nome, dimensioni in byte e un collegamento per scaricarlo.

Formato API

GET /files/{FILE_ID}
Proprietà Descrizione
{FILE_ID} Identificatore del file a cui si desidera accedere.

Richiesta

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

A seconda che l’ID del file punti a un singolo file o a una directory, l’array di dati restituito può contenere una singola voce o un elenco di file appartenenti a tale directory. Ogni elemento del file conterrà dettagli quali il nome del file, la dimensione in byte e un collegamento per scaricare il file.

Caso 1: L'ID del file punta a un singolo file

Risposta

{
    "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
    }
}
Proprietà Descrizione
{FILE_NAME}.parquet Nome del file.
_links.self.href URL per scaricare il file.

Caso 2: L'ID del file punta a una directory

Risposta

{
    "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
    }
}
Proprietà Descrizione
data._links.self.href URL per scaricare il file associato.

Questa risposta restituisce una directory contenente due file separati, con ID {FILE_ID_2} e {FILE_ID_3}. In questo scenario, per accedere al file dovrai seguire l’URL di ciascun file .

Recupera i metadati di un file

È possibile recuperare i metadati di un file effettuando una richiesta di HEAD. Questo restituisce le intestazioni dei metadati del file, incluse le dimensioni in byte e il formato del file.

Formato API

HEAD /files/{FILE_ID}?path={FILE_NAME}
Proprietà Descrizione
{FILE_ID} Identificatore del file.
{FILE_NAME} Nome del file (ad esempio, profiles.parquet)

Richiesta

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

Risposta

Le intestazioni di risposta contengono i metadati del file interrogato, tra cui:

  • Content-Length: Indica la dimensione del payload in byte
  • Content-Type: Indica il tipo di file.

Accedere al contenuto di un file

Puoi anche accedere al contenuto di un file utilizzando l’ Data Access API .

Formato API

GET /files/{FILE_ID}?path={FILE_NAME}
Proprietà Descrizione
{FILE_ID} Identificatore del file.
{FILE_NAME} Il nome del file (ad esempio, profiles.parquet).

Richiesta

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

Risposta

Una risposta corretta restituisce il contenuto del file.

Scaricare il contenuto parziale di un file

L’ API Data Access consente di scaricare i file in blocchi. È possibile specificare un'intestazione di intervallo durante una richiesta GET /files/{FILE_ID} per scaricare un intervallo specifico di byte da un file. Se l’intervallo non è specificato, l’API scaricherà l’intero file per impostazione predefinita.

L'esempio di HEAD nella sezione precedente indica la dimensione di un file specifico in byte.

Formato API

GET /files/{FILE_ID}?path={FILE_NAME}
Proprietà Descrizione
{FILE_ID} Identificatore del file.
{FILE_NAME} Nome del file (ad esempio, profiles.parquet)

Richiesta

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'
Proprietà Descrizione
Range: bytes=0-99 Specifica l'intervallo di byte da scaricare. Se non viene specificato, l’API scaricherà l’intero file. In questo esempio verranno scaricati i primi 100 byte.

Risposta

Il corpo della risposta include i primi 100 byte del file (come specificato dall'intestazione "Range" nella richiesta) insieme allo stato HTTP 206 (Contenuti parziali). La risposta include anche le seguenti intestazioni:

  • Lunghezza del contenuto: 100 (il numero di byte restituiti)
  • Tipo di contenuto: application/parquet (è stato richiesto un file Parquet, pertanto il tipo di contenuto della risposta è parquet)
  • Intervallo di contenuti: byte 0-99/249058 (l'intervallo richiesto (0-99) sul numero totale di byte (249058))

Configurare l’impaginazione delle risposte API

Le risposte all’interno dell’ API Data Access sono impaginate. Per impostazione predefinita, il numero massimo di voci per pagina è 100. I parametri di paging possono essere utilizzati per modificare il comportamento predefinito.

  • limit: Puoi specificare il numero di voci per pagina in base alle tue esigenze utilizzando il parametro "limit" (Limite).
  • start: L'offset può essere impostato dal parametro di query "start".
  • &: Puoi utilizzare una e commerciale per combinare più parametri in una singola chiamata.

Formato API

GET /batches/{BATCH_ID}/files?start={OFFSET}
GET /batches/{BATCH_ID}/files?limit={LIMIT}
GET /batches/{BATCH_ID}/files?start={OFFSET}&limit={LIMIT}
Proprietà Descrizione
{BATCH_ID} Identificatore batch del batch a cui si sta tentando di accedere.
{OFFSET} Indice specificato per avviare la matrice dei risultati (ad esempio, start=0)
{LIMIT} Controlla quanti risultati vengono restituiti nella matrice dei risultati (ad esempio, limit=1)

Richiesta

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

Risposta:

La risposta contiene un array "data" con un singolo elemento, come specificato dal parametro di richiesta limit=1. Questo elemento è un oggetto contenente i dettagli del primo file disponibile, come specificato dal parametro start=0 nella richiesta (ricorda che nella numerazione basata su zero, il primo elemento è “0”).

Il valore _links.next.href contiene il collegamento alla pagina successiva di risposte, dove puoi vedere che il parametro start è stato avanzato per 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
        }
    }
}

In questa pagina