Guida alla risoluzione dei problemi di inserimento in batch

Questa documentazione risponde alle domande frequenti sulle API di Adobe Experience Platform Batch Data Ingestion.

Chiamate API in batch

I batch sono attivi immediatamente dopo aver ricevuto un OK HTTP 200 dall’API CompleteBatch?

La risposta 200 OK dall'API indica che il batch è stato accettato per l'elaborazione - non è attivo fino a quando non passa al suo stato finale, ad esempio Attivo o Errore.

È sicuro riprovare la chiamata API CompleteBatch dopo l'errore?

Sì: puoi riprovare la chiamata API. Nonostante il guasto, è possibile che l'operazione sia riuscita effettivamente e il batch è stato accettato con successo. Tuttavia, i client devono disporre di meccanismi per l’esecuzione di nuovi tentativi in caso di errore dell’API e, di fatto, devono riprovare. Se l’operazione ha avuto successo, l’API restituisce il successo, anche dopo un nuovo tentativo.

Quando deve essere utilizzata l’API di caricamento file di grandi dimensioni?

La dimensione file consigliata per l’utilizzo dell’API per il caricamento di file di grandi dimensioni è pari o superiore a 256 MB. Ulteriori informazioni sull'utilizzo dell'API di caricamento file di grandi dimensioni sono disponibili qui.

Perché la chiamata API Large File Complete non riesce?

Se vengono trovati blocchi di un file di grandi dimensioni sovrapposti o mancanti, il server risponde con una richiesta HTTP 400 Bad. Questo può verificarsi perché è possibile caricare blocchi sovrapposti, poiché le convalide degli intervalli vengono eseguite al momento del completamento del file, quando i blocchi di file sono uniti.

Supporto per l’acquisizione

Quali sono i formati di acquisizione supportati?

Attualmente, sono supportati sia Parquet che JSON. Il CSV è supportato su base legacy; i dati verranno promossi a master e verranno eseguiti controlli preliminari; non saranno supportate funzioni moderne, ad esempio conversione, partizionamento o convalida delle righe.

Dove specificare il formato di input batch?

Il formato di input deve essere specificato al momento della creazione del batch all'interno del payload. Di seguito è riportato un esempio di come specificare il formato di input batch:

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json"
           }
    }'

Perché i dati caricati non vengono visualizzati nel set di dati?

Affinché i dati vengano visualizzati nel set di dati, il batch deve essere contrassegnato come completo. Tutti i file da acquisire devono essere caricati prima di contrassegnare il batch come completo. Di seguito è riportato un esempio di marcatura completa di un batch:

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Come viene acquisito JSON multi-riga?

Per acquisire JSON con più righe, il flag isMultiLineJson deve essere impostato al momento della creazione del batch. Di seguito è riportato un esempio:

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json",
                "isMultiLineJson": true
           }
      }'

Qual è la differenza tra le righe JSON (JSON a riga singola) e JSON a riga singola?

Per le righe JSON esiste un oggetto JSON per riga. Esempio:

{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}

Per JSON su più righe, un oggetto può occupare più righe, mentre tutti gli oggetti sono racchiusi in un array JSON. Esempio:

[
    {"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
    {"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
    {
        "string": "string3",
        "int": 3,
        "array": [
            3,
            6,
            9
        ],
        "dict": {
            "key": "value3",
            "extra_key": "extra_value3"
        }
    }
]

Per impostazione predefinita, Batch Data Ingestion utilizza JSON a riga singola.

L’acquisizione CSV è supportata?

L’acquisizione CSV è supportata solo per gli schemi piatti. Al momento, l’acquisizione di dati gerarchici in CSV non è supportata.

Per ottenere tutte le funzioni di acquisizione dei dati, è necessario utilizzare i formati JSON o Parquet.

Quali tipi di convalida vengono eseguiti sui dati?

I dati vengono convalidati in tre livelli:

• Schema: l’acquisizione in batch assicura che lo schema dei dati acquisiti corrisponda allo schema del set di dati.
• Tipo di dati : l’acquisizione in batch assicura che il tipo per ciascun campo acquisito corrisponda al tipo definito nello schema del set di dati.
• Vincoli: l’acquisizione in batch assicura che i vincoli, come "Obbligatorio", "enum" e "formato", siano definiti correttamente nella definizione dello schema.

Come può essere sostituito un batch già acquisito?

È possibile sostituire un batch già acquisito utilizzando la funzione Riproduzione batch. Ulteriori informazioni sulla riproduzione in batch sono disponibili qui.

Come viene monitorata l’acquisizione batch?

Una volta che un batch è stato segnalato per la promozione batch, l'avanzamento dell'acquisizione batch può essere monitorato con la seguente richiesta:

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

Con questa richiesta riceverai una risposta simile a questa:

200 OK

{
    "{BATCH_ID}":{
        "imsOrg":"{IMS_ORG}",
        "created":1494349962314,
        "createdClient":"{API_KEY}",
        "createdUser":"{USER_ID}",
        "updatedUser":"{USER_ID}",
        "completed":1494349963467,
        "externalId":"{EXTERNAL_ID}",
        "status":"staging",
        "errors":[],
    }
}

Stati batch

Quali sono i possibili stati batch?

Un batch può, nel suo ciclo di vita, superare i seguenti stati:

Cosa significa "staging" per i batch?

Quando un batch si trova in "Staging", significa che il batch è stato segnalato con successo per la promozione e che i dati sono in fase di staging per il consumo a valle.

Cosa significa quando un batch è "Nuovo tentativo"?

Quando un batch si trova in "Nuovo tentativo", significa che l'inserimento dei dati del batch è stato temporaneamente interrotto a causa di problemi intermittenti. In questo caso, non richiede alcun intervento da parte del cliente.

Cosa significa quando un batch è "Bloccato"?

Quando un batch si trova in "Bloccato", significa che Data Ingestion Services sta riscontrando difficoltà nell’acquisizione del batch e tutti i tentativi sono stati esauriti.

Cosa significa se un batch è ancora "Caricamento"?

Quando un batch è in "Caricamento", significa che l'API CompleteBatch non è stata chiamata per promuovere il batch.

Esiste un modo per sapere se un batch è stato acquisito correttamente?

Una volta che lo stato del batch è "Attivo", il batch è stato acquisito correttamente. Per scoprire lo stato del batch, segui i passaggi descritti in Precedente.

Cosa succede dopo un errore di un batch?

Quando un batch non riesce, il motivo per cui non riesce può essere identificato nella sezione errors del payload. Di seguito sono riportati alcuni esempi di errori:

    "errors":[
        {
            "code":"106",
            "description":"Dataset file is empty. Please upload file with data.",
            "rows":[]
        },
        {
            "code":"118",
            "description":"CSV file contains empty header row.",
            "rows":[]
        }
    ]

Una volta corretti gli errori, il batch può essere ricaricato.

Supporto batch

Come eliminare i batch?

Invece di eliminare direttamente da Catalog, i batch devono essere rimossi utilizzando uno dei metodi seguenti:

1. Se il batch è in corso, il batch deve essere interrotto.
2. Se il batch viene gestito correttamente, il batch deve essere ripristinato.

Quali metriche a livello di batch sono disponibili?

Le seguenti metriche a livello di batch sono disponibili per i batch nello stato Attivo/Successo:

Perché le metriche non sono disponibili su alcuni batch?

Esistono due motivi per cui le metriche potrebbero non essere disponibili nel batch:

1. Il batch non è mai stato eseguito correttamente nello stato Attivo/Successo.
2. Il batch è stato promosso utilizzando un percorso di promozione legacy, ad esempio l’acquisizione CSV.

Cosa significano i diversi codici di stato?