Documentazione Experience Platform Guida all’accesso ai dati

Visualizzare i dati del set di dati tramite Data Access API

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

Argomenti:
Data Access

Creato per:

Developer

Utilizza questo tutorial per scoprire come individuare, accedere e scaricare i dati memorizzati all’interno di un set di dati utilizzando Data Access API in Adobe Experience Platform. Questo documento introduce alcune delle funzionalità esclusive di Data Access API, come il paging e i download parziali.

Introduzione

Questo tutorial richiede una buona conoscenza di come creare e popolare un set di dati. Consulta la tutorial sulla creazione di set di dati per ulteriori informazioni.

Le sezioni seguenti forniscono informazioni aggiuntive di cui hai bisogno per effettuare correttamente le chiamate alle API di Platform.

Lettura delle chiamate API di esempio reading-sample-api-calls

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

Raccogliere i valori per le intestazioni richieste

Per effettuare chiamate a Platform , devi prima completare le tutorial sull’autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

Autorizzazione: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Tutte le risorse in Experience Platform sono isolati in specifiche sandbox virtuali. Tutte le richieste a Platform Le API richiedono un’intestazione che specifichi il nome della sandbox in cui si svolge l’operazione:

x-sandbox-name: {SANDBOX_NAME}

NOTE

Per ulteriori informazioni sulle sandbox in Platform, vedere documentazione di panoramica sulla sandbox.

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

Content-Type: application/json

Diagramma sequenza

Questa esercitazione segue i passaggi descritti nel diagramma di sequenza riportato di seguito, evidenziando le funzionalità principali di Data Access API.

Un diagramma di sequenza della funzionalità di base dell’API di accesso ai dati.

Per recuperare informazioni relative a batch e file, utilizzare Catalog API. Per accedere e scaricare questi file tramite HTTP come download completi o parziali, a seconda delle dimensioni del file, utilizza Data Access API.

Individuare i dati

Prima di iniziare a utilizzare il Data Access API, devi identificare la posizione dei dati a cui desideri accedere. In Catalog API, puoi utilizzare due endpoint per sfogliare i metadati di un’organizzazione e recuperare l’ID di un batch o di un file a cui desideri accedere:

GET /batches: restituisce un elenco di batch nell’organizzazione
GET /dataSetFiles: restituisce un elenco di file dell’organizzazione

Per un elenco completo degli endpoint nel Catalog API, fai riferimento alla Riferimento API.

Recuperare un elenco di batch nell'organizzazione

Utilizzo di Catalog API, puoi restituire un elenco di batch all’interno della tua 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

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

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

Filtrare l’elenco dei batch filter-batches-list

I filtri sono spesso necessari per trovare un particolare batch per recuperare dati rilevanti per un particolare caso d’uso. I parametri possono essere aggiunti a una GET /batches richiesta di 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 al momento della creazione.

Formato API

GET /batches?createdAfter={START_TIMESTAMP}&dataSet={DATASET_ID}&sort={SORT_BY}

Proprietà

Descrizione

{START_TIMESTAMP}

Il timestamp di inizio in millisecondi (ad esempio, 1514836799000).

{DATASET_ID}

L’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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

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

Un elenco completo dei parametri e dei filtri è disponibile nella sezione Riferimento API catalogo.

Recuperare un elenco di tutti i file appartenenti a un batch specifico

Ora che disponi dell’ID del batch a cui desideri accedere, puoi utilizzare Data Access API 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: {ORG_ID}' \
  -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 di accesso al file.

La risposta contiene un array di dati che elenca tutti i file all’interno del batch specificato. I file sono referenziati dal loro ID file, che si trova sotto dataSetFileId campo.

Accedere a un file utilizzando un ID file access-file-with-file-id

Una volta che hai un ID file univoco, puoi utilizzare Data Access API per accedere ai dettagli specifici sul file, tra cui il nome, la dimensione 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

A seconda che l’ID 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 contiene dettagli quali il nome del file, la dimensione in byte e un collegamento per scaricare il file.

Caso 1: l’ID 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 il download del file.

Caso 2: l’ID 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 caso, devi seguire l’URL di ciascun file per accedere al file.

Recuperare i metadati di un file

Per recuperare i metadati di un file, effettua una richiesta HEAD. In questo modo vengono restituite le intestazioni di metadati del file, incluse le dimensioni in byte e nel formato di file.

Formato API

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

Risposta

Le intestazioni di risposta contengono i metadati del file sottoposto a query, tra cui:

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

Accedere al contenuto di un file

È inoltre possibile accedere al contenuto di un file utilizzando 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce il contenuto del file.

Scaricare il contenuto parziale di un file download-partial-file-contents

Per scaricare un intervallo specifico di byte da un file, specificare un'intestazione di intervallo durante un GET /files/{FILE_ID} richiesta al Data Access API. Se l’intervallo non è specificato, l’API scarica l’intero file per impostazione predefinita.

L’esempio di HEAD in sezione precedente fornisce 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}

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: {ORG_ID}' \
  -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 scarica l’intero file. In questo esempio vengono 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:

Content-Length: 100 (numero di byte restituiti)
Tipo di contenuto: applicazione/parquet (è stato richiesto un file Parquet, pertanto il tipo di contenuto della risposta è parquet)
Content-Range: byte 0-99/249058 (l'intervallo richiesto (0-99) del numero totale di byte (249058))

Configurare l’impaginazione della risposta API configure-response-pagination

Risposte all’interno di Data Access API impaginate. Per impostazione predefinita, il numero massimo di voci per pagina è 100. Potete modificare il comportamento predefinito con i parametri di paging.

limit: puoi specificare il numero di voci per pagina in base alle tue esigenze utilizzando il parametro "limit".
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}

L'indice specificato per avviare la matrice dei risultati (ad esempio, start=0)

{LIMIT}

Controlla il numero di risultati 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta:

La risposta contiene un "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 da start=0 nella richiesta (ricorda che nella numerazione basata su zero il primo elemento è "0").

Il _links.next.href contiene il collegamento alla pagina successiva delle risposte, in cui è possibile vedere che start il parametro è stato avanzato fino 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