Panoramica sull’assimilazione dei batch

L'API Adobe Experience Platform Data Ingestion consente di trasferire i dati nella piattaforma come file batch. I dati che si desidera acquisire possono essere i dati di profilo provenienti da un file semplice in un sistema CRM (ad esempio un file Parquet), o i dati conformi a uno schema noto nel Registro di sistema Experience Data Model (XDM).

Il riferimento API Data Ingestion fornisce informazioni aggiuntive su queste chiamate API.

Il diagramma seguente illustra il processo di assimilazione dei batch:

Utilizzo dell'API

L'API Data Ingestion consente di assimilare i dati come batch (un'unità di dati costituita da uno o più file da assimilare come singola unità) in Experience Platform in tre passaggi fondamentali:

  1. Creare un nuovo batch.
  2. Caricate i file in un set di dati specificato che corrisponde allo schema XDM dei dati.
  3. Segnala la fine del batch.

Data Ingestion prerequisiti

  • I dati da caricare devono essere in formato Parquet o JSON.
  • Un dataset creato in Catalog services.
  • Il contenuto del file Parquet deve corrispondere a un sottoinsieme dello schema del set di dati in fase di caricamento.
  • Dopo l'autenticazione, avrai il tuo token di accesso univoco.

Best practice per l’assimilazione dei batch

  • La dimensione del batch consigliata è compresa tra 256 MB e 100 GB.
  • Ogni batch deve contenere al massimo 1500 file.

Per caricare un file di dimensioni superiori a 512 MB, è necessario dividere il file in blocchi più piccoli. Le istruzioni per caricare un file di grandi dimensioni sono disponibili in qui.

Lettura di chiamate API di esempio

Questa guida 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 JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consultate la sezione relativa a come leggere chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform.

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle Platform API, è innanzitutto necessario completare l'esercitazione sull'autenticazione a2/>. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come illustrato 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 Platform API richiedono un'intestazione che specifica il nome della sandbox in cui verrà eseguita l'operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

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

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

  • Content-Type: application/json

Creare un batch

Prima di poter aggiungere dati a un dataset, questi devono essere collegati a un batch, che verrà poi caricato in un set di dati specificato.

POST /batches

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "Content-Type: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"
  -d '{ 
          "datasetId": "{DATASET_ID}" 
      }'
Proprietà Descrizione
datasetId ID del set di dati in cui caricare i file.

Risposta

{
    "id": "{BATCH_ID}",
    "imsOrg": "{IMS_ORG}",
    "updated": 0,
    "status": "loading",
    "created": 0,
    "relatedObjects": [
        {
            "type": "dataSet",
            "id": "{DATASET_ID}"
        }
    ],
    "version": "1.0.0",
    "tags": {},
    "createdUser": "{USER_ID}",
    "updatedUser": "{USER_ID}"
}
Proprietà Descrizione
id ID del batch appena creato (utilizzato nelle richieste successive).
relatedObjects.id ID del set di dati in cui caricare i file.

Caricamento file

Dopo aver creato un nuovo batch per il caricamento, i file possono essere caricati in un set di dati specifico.

Potete caricare i file mediante l’API di caricamento dei file di dimensioni ridotte. Tuttavia, se i file sono troppo grandi e il limite del gateway viene superato (ad esempio timeout estesi, richieste di dimensioni del corpo superate e altre restrizioni), potete passare all'API di caricamento dei file di grandi dimensioni. Questa API carica il file in blocchi e unisce i dati utilizzando la chiamata API Large File Upload Complete.

NOTA

Gli esempi seguenti utilizzano il formato di file Apache Parquet. Un esempio che utilizza il formato di file JSON si trova nella guida per gli sviluppatori di assimilazione batch.

Caricamento di file di piccole dimensioni

Una volta creato un batch, i dati possono essere caricati in un dataset preesistente. Il file caricato deve corrispondere allo schema XDM di riferimento.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Proprietà Descrizione
{BATCH_ID} ID del batch.
{DATASET_ID} ID del set di dati per caricare i file.
{FILE_NAME} Nome del file che verrà visualizzato nel set di dati.

Richiesta

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Proprietà Descrizione
{FILE_PATH_AND_NAME} Percorso e nome del file da caricare nel dataset.

Risposta

#Status 200 OK, with empty response body

Caricamento di file di grandi dimensioni - creazione di file

Per caricare un file di grandi dimensioni, il file deve essere suddiviso in blocchi più piccoli e caricato uno alla volta.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize
Proprietà Descrizione
{BATCH_ID} ID del batch.
{DATASET_ID} L’ID del set di dati per l’assimilazione dei file.
{FILE_NAME} Nome del file che verrà visualizzato nel set di dati.

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

#Status 201 CREATED, with empty response body

Caricamento di file di grandi dimensioni - caricamento di parti successive

Dopo la creazione del file, tutti i blocchi successivi possono essere caricati effettuando ripetute richieste di PATCH, una per ogni sezione del file.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Proprietà Descrizione
{BATCH_ID} ID del batch.
{DATASET_ID} ID del set di dati in cui caricare i file.
{FILE_NAME} Nome del file che verrà visualizzato nel set di dati.

Richiesta

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Proprietà Descrizione
{FILE_PATH_AND_NAME} Percorso e nome del file da caricare nel dataset.

Risposta

#Status 200 OK, with empty response

Completamento batch segnale

Dopo aver caricato tutti i file nel batch, il batch può essere segnalato per il completamento. A questo scopo, le Catalog voci DataSetFile vengono create per i file completati e associate al batch generato in precedenza. Il batch Catalog viene quindi contrassegnato come riuscito, che attiva i flussi a valle per l'acquisizione dei dati disponibili.

Richiesta

POST /batches/{BATCH_ID}?action=COMPLETE
Proprietà Descrizione
{BATCH_ID} ID del batch da caricare nel set di dati.
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"

Risposta

#Status 200 OK, with empty response

Verifica stato batch

In attesa del caricamento dei file nel batch, è possibile controllare lo stato del batch per verificarne l'avanzamento.

Formato API

GET /batch/{BATCH_ID}
Proprietà Descrizione
{BATCH_ID} ID del batch da controllare.

Richiesta

curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Risposta

{
    "{BATCH_ID}": {
        "imsOrg": "{IMS_ORG}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}
Proprietà Descrizione
{USER_ID} L'ID dell'utente che ha creato o aggiornato il batch.

Il campo "status" indica lo stato corrente del batch richiesto. I batch possono avere uno dei seguenti stati:

Stati di inserimento batch

Stato Descrizione
Abbandonato Il batch non è stato completato nel periodo di tempo previsto.
Interrotto Un'operazione di interruzione è stata chiamata esplicitamente (tramite l'API Batch Ingest) per il batch specificato. Una volta che il batch è in stato "Caricato", non può essere interrotto.
Attivo Il batch è stato promosso con successo ed è disponibile per il consumo a valle. Questo stato può essere utilizzato in modo intercambiabile con "Success".
Eliminato I dati per il batch sono stati rimossi completamente.
Non riuscito Uno stato terminale che risulta da una configurazione non corretta e/o da dati non corretti. I dati per un batch con errore non verranno visualizzati. Questo stato può essere utilizzato in modo intercambiabile con "Errore".
Inattivo Il batch è stato promosso con successo, ma è stato ripristinato o è scaduto. Il batch non è più disponibile per il consumo a valle.
Caricato I dati per il batch sono completi e il batch è pronto per la promozione.
Caricamento I dati per questo batch vengono caricati e il batch è attualmente not pronto per essere promosso.
Nuovo Elaborazione dei dati per questo batch in corso. Tuttavia, a causa di un errore di sistema o temporaneo, il batch non è riuscito, come risultato, il batch viene riprovato.
In pila La fase intermedia del processo di promozione per un batch è completa e il processo di assimilazione è stato eseguito.
Staging Elaborazione dei dati per il batch in corso.
Bloccato Elaborazione dei dati per il batch in corso. Tuttavia, la promozione batch si è arrestata dopo diversi tentativi.

In questa pagina

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now