Panoramica dell’API per l’acquisizione in batch

L’API per l’acquisizione in batch di Adobe Experience Platform consente di acquisire i dati in Platform come file batch. I dati da acquisire possono essere dati di profilo da un file flat (ad esempio un file Parquet) o dati conformi a uno schema noto nel registro Experience Data Model (XDM).

Il riferimento all'API acquisizione batch fornisce informazioni aggiuntive su queste chiamate API.

Il diagramma seguente illustra il processo di acquisizione batch:

Introduzione

Gli endpoint API utilizzati in questa guida fanno parte dell'API di acquisizione batch. Prima di continuare, consulta la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e per le informazioni importanti sulle intestazioni necessarie per effettuare correttamente le chiamate a qualsiasi API di Experience Platform.

Data Ingestion prerequisiti

  • I dati da caricare devono essere in formato Parquet o JSON.
  • Un set di dati creato in Catalog services.
  • Il contenuto del file Parquet deve corrispondere a un sottoinsieme dello schema del set di dati in cui viene caricato.
  • Disporre di un token di accesso univoco dopo l’autenticazione.

Best practice per l’acquisizione in batch

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

Vincoli di acquisizione in batch

L’acquisizione di dati batch presenta alcuni vincoli:

  • Numero massimo di file per batch: 1500
  • Dimensione massima batch: 100 GB
  • Numero massimo di proprietà o campi per riga: 10000
  • Numero massimo di batch nel data lake al minuto per utente: 2000
NOTE
Per caricare un file di dimensioni superiori a 512 MB, è necessario suddividerlo in blocchi più piccoli. Le istruzioni per caricare un file di grandi dimensioni sono disponibili nella sezione caricamento file di grandi dimensioni di questo documento.

Tipi

Durante l'acquisizione dei dati, è importante comprendere come funzionano gli schemi Experience Data Model (XDM). Per ulteriori informazioni sul modo in cui i tipi di campo XDM vengono mappati su formati diversi, consulta la Guida per gli sviluppatori del registro dello schema.

È disponibile una certa flessibilità durante l’acquisizione dei dati: se un tipo non corrisponde a quello presente nello schema di destinazione, i dati verranno convertiti nel tipo di destinazione espresso. In caso contrario, il batch non riuscirà con TypeCompatibilityException.

Ad esempio, né JSON né CSV hanno un tipo date o date-time. Di conseguenza, questi valori vengono espressi utilizzando stringhe formattate ISO 8601 ("2018-07-10T15:05:59.000-08:00") o ora Unix formattate in millisecondi (1531263959000) e vengono convertiti al momento dell'acquisizione nel tipo XDM di destinazione.

La tabella seguente mostra le conversioni supportate durante l’acquisizione dei dati.

In entrata (riga) e Target (colonna)
Stringa
Byte
Breve
Intero
Lungo
Doppio
Data
Data-ora
Oggetto
Mappa
Stringa
X
X
X
X
X
X
X
X
Byte
X
X
X
X
X
X
Breve
X
X
X
X
X
X
Intero
X
X
X
X
X
X
Lungo
X
X
X
X
X
X
X
X
Doppio
X
X
X
X
X
X
Data
X
Data-ora
X
Oggetto
X
X
Mappa
X
X
NOTE
I booleani e gli array non possono essere convertiti in altri tipi.

Mediante l’API

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

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

Creare un batch

Prima di poter aggiungere dati a un set di dati, questi devono essere collegati a un batch, che in seguito verrà 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: {ORG_ID}" \
  -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": "{ORG_ID}",
    "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 di file

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

Puoi caricare i file utilizzando l’API Caricamento file di piccole dimensioni. 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 limitazioni), puoi passare all’API di caricamento file di grandi dimensioni. Questa API carica il file in blocchi e unisce i dati utilizzando la chiamata API Caricamento di file di grandi dimensioni completato.

NOTE
L’acquisizione batch può essere utilizzata per aggiornare in modo incrementale i dati nell’archivio profili. Per ulteriori informazioni, vedere la sezione relativa all'aggiornamento di un batch🔗 nella guida per gli sviluppatori per l'acquisizione batch.
INFO
Gli esempi seguenti utilizzano il formato di file Apache Parquet. Un esempio che utilizza il formato di file JSON è disponibile nella guida per gli sviluppatori sull'acquisizione batch.

Caricamento di file di piccole dimensioni

Una volta creato un batch, i dati possono essere caricati in un set di dati preesistente. Il file caricato deve corrispondere al relativo 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 come 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: {ORG_ID}" \
  -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 set di dati.

Risposta

#Status 200 OK, with empty response body

Caricamento di file di grandi dimensioni - Crea file

Per caricare un file di grandi dimensioni, il file deve essere diviso 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}
ID del set di dati che acquisisce i file.
{FILE_NAME}
Nome del file come 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: {ORG_ID}" \
  -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 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: {ORG_ID}" \
  -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 set di dati.

Risposta

#Status 200 OK, with empty response

Completamento batch segnale

Dopo che tutti i file sono stati caricati nel batch, il batch può essere segnalato per il completamento. In questo modo, vengono create le voci di DataSetFile Catalog per i file completati e associate al batch generato in precedenza. Il batch Catalog è quindi contrassegnato come riuscito, che attiva i flussi a valle per acquisire i 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: {ORG_ID}" \
-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 che i file vengano caricati 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: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Risposta

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "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}
ID dell’utente che ha creato o aggiornato il batch.

Il campo "status" è quello che mostra lo stato corrente del batch richiesto. I batch possono avere uno dei seguenti stati:

Stati di acquisizione in batch

Stato
Descrizione
Abbandonato
Il batch non è stato completato entro il periodo di tempo previsto.
Interrotto
È stata chiamata esplicitamente un'operazione di interruzione (tramite Batch Ingest API) per il batch specificato. Una volta che il batch è in uno stato "Loaded" (Caricato), non può essere interrotto.
Attivo
Il batch è stato promosso correttamente ed è disponibile per il consumo a valle. Questo stato può essere utilizzato in modo intercambiabile con "Success" (Completato).
Eliminato
I dati per il batch sono stati completamente rimossi.
Non riuscito
Stato del terminale causato da configurazione e/o dati non validi. I dati per un batch non riuscito non verranno visualizzati. Questo stato può essere utilizzato in modo intercambiabile con "Errore".
Non attivo
Il batch è stato promosso correttamente, 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 in corso
I dati per questo batch sono in fase di caricamento e il batch è attualmente non pronto per essere promosso.
Nuovo tentativo
Elaborazione dei dati per questo batch in corso. Tuttavia, a causa di un errore di sistema o transitorio, il batch non è riuscito. Di conseguenza, si sta tentando di nuovo di eseguire il batch.
Staging
La fase di staging del processo di promozione per un batch è stata completata e il processo di acquisizione è stato eseguito.
Staging
Dati per il batch in fase di elaborazione.
Bloccato
I dati per il batch sono in fase di elaborazione. Tuttavia, la promozione batch si è bloccata dopo una serie di tentativi.
recommendation-more-help
2ee14710-6ba4-4feb-9f79-0aad73102a9a