Show Menu
ARGOMENTI×

Iniezione batch parziale (versione beta)

L'assimilazione parziale dei batch è la capacità di assimilare i dati contenenti errori, fino a una determinata soglia. Grazie a questa funzionalità, gli utenti possono trasferire con successo tutti i dati corretti in Adobe Experience Platform mentre tutti i dati errati vengono inseriti in batch separatamente, insieme ai dettagli sul motivo per cui non sono validi.
Questo documento fornisce un’esercitazione per la gestione dell’assimilazione parziale dei batch.
Inoltre, l' appendice di questa esercitazione fornisce un riferimento per i tipi di errori di caricamento batch parziale.
Questa funzione esiste solo utilizzando l'API. Per accedere a questa funzione, contattate il team.

Introduzione

Questa esercitazione richiede una buona conoscenza dei diversi servizi Adobe Experience Platform coinvolti nell'assimilazione parziale dei batch. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi:
  • Caricamento batch: Il metodo che la piattaforma acquisisce e memorizza i dati dai file di dati, come CSV e Parquet.
  • Experience Data Model (XDM) : Il framework standardizzato tramite il quale la piattaforma organizza i dati sull'esperienza cliente.
Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per effettuare correttamente chiamate alle API della piattaforma.

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, consulta la sezione come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi della piattaforma Experience.

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle API della piattaforma, dovete prima completare l'esercitazione di autenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di 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 API della piattaforma richiedono un'intestazione che specifica il nome della sandbox in cui avrà luogo l'operazione:
  • x-sandbox-name: {SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Piattaforma, consultate la documentazione sulla panoramica della sandbox.

Abilitare un set di dati per l'assimilazione parziale dei batch nell'API

È possibile creare un nuovo set di dati o modificare un set di dati esistente con l'inserimento parziale abilitato.
Per creare un nuovo set di dati, seguite i passaggi descritti nell'esercitazione sulla creazione di un set di dati. Una volta raggiunto il passaggio Crea un dataset , aggiungi il seguente campo all’interno del corpo della richiesta:
{
    ...
    "tags" : {
        "partialBatchIngestion":["errorThresholdPercentage:5"]
    },
    ...
}

Proprietà
Descrizione
errorThresholdPercentage
Percentuale di errori accettabili prima che l'intero batch non riesca.
Analogamente, per modificare un dataset esistente, seguite i passaggi descritti nella guida per gli sviluppatori del catalogo.
All'interno del set di dati, dovrete aggiungere il tag descritto in precedenza.

Recupero degli errori di caricamento batch parziale

Se i batch contengono errori, sarà necessario recuperare le informazioni di errore relative a tali errori in modo da poter nuovamente assimilare i dati.

Verifica stato

Per verificare lo stato del batch assimilato, dovete fornire l'ID del batch nel percorso di una richiesta GET.
Formato API
GET /catalog/batches/{BATCH_ID}

Parametro
Descrizione
{BATCH_ID}
Il id valore del batch di cui si desidera controllare lo stato.
Richiesta
curl -X GET https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID} \
  -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 lo stato HTTP 200 con informazioni dettagliate sullo stato del batch.
{
    "af838510-2233-11ea-acf0-f3edfcded2d2": {
        "status": "success",
        "tags": {
            ...
        },
        "relatedObjects": [
            {
                "type": "dataSet",
                "id": "5deac2648a19d218a888d2b1"
            }
        ],
        "id": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "externalId": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "inputFormat": {
            "format": "parquet"
        },
        "imsOrg": "{IMS_ORG}",
        "started": 1576741718543,
        "metrics": {
            "inputByteSize": 568,
            "inputFileCount": 4,
            "inputRecordCount": 519,
            "outputRecordCount": 497
        },
        "completed": 1576741722026,
        "created": 1576741597205,
        "createdClient": "{API_KEY}",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1576741722644,
        "version": "1.0.5"
    }    
}

Se il batch presenta un errore e la diagnostica degli errori è abilitata, lo stato sarà "success" con ulteriori informazioni sull'errore fornito in un file di errore scaricabile.

Passaggi successivi

In questa esercitazione è stato illustrato come creare o modificare un dataset per abilitare l’assimilazione parziale dei batch. Per ulteriori informazioni sull'assimilazione batch, leggere la guida per gli sviluppatori di inserimento batch.

Tipi di errori di assimilazione parziale dei batch

L’assimilazione parziale dei batch presenta quattro tipi di errore diversi durante l’assimilazione dei dati.

File illeggibili

Se il batch ingerito contiene file illeggibili, gli errori del batch verranno allegati al batch stesso. Ulteriori informazioni sul recupero del batch non riuscito sono disponibili nella guida al recupero dei batch non riusciti.

Schemi o intestazioni non validi

Se lo schema del batch ingerito non è valido o le intestazioni non sono valide, gli errori del batch verranno collegati al batch stesso. Ulteriori informazioni sul recupero del batch non riuscito sono disponibili nella guida al recupero dei batch non riusciti.

Righe non analizzabili

Se il batch ingerito contiene righe non analizzabili, gli errori del batch verranno memorizzati in un file a cui è possibile accedere utilizzando l'endpoint indicato di seguito.
Formato API
GET /export/batches/{BATCH_ID}/failed?path=parse_errors

Parametro
Descrizione
{BATCH_ID}
Il id valore del batch da cui si recuperano le informazioni sull'errore.
Richiesta
curl -X GET https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path=parse_errors \
  -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 lo stato HTTP 200 con i dettagli delle righe non analizzabili.
{
    "_corrupt_record":"{missingQuotes:"v1"}",
    "_errors": [{
         "code":"1401",
         "message":"Row is corrupted and cannot be read, please fix and resend."
    }],
    "_filename": "a1.json"
}

Conversione XDM non valida

Se il batch ingerito contiene conversioni XDM non valide, gli errori del batch verranno memorizzati in un file a cui è possibile accedere utilizzando il seguente endpoint.
Formato API
GET /export/batches/{BATCH_ID}/failed?path=conversion_errors

Parametro
Descrizione
{BATCH_ID}
Il id valore del batch da cui si recuperano le informazioni sull'errore.
Richiesta
curl -X GET https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path=conversion_errors \
  -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 lo stato HTTP 200 con dettagli sugli errori di conversione XDM.
{
    "col1":"v1",
    "col2":"v2",
    "col3":[{
        "g1":"h1"
    }],
    "_errors":[{
        "column":"col3",
        "code":"123",
        "message":"Cannot convert array element from Object to String"
    }],
    "_filename":"a1.json"
},
{
    "col1":"v1",
    "col2":"v2",
    "col3":[{
        "g1":"h1"
    }],
    "_errors":[{
        "column":"col1",
        "code":"100",
        "message":"Cannot convert string to float"
    }],
    "_filename":"a2.json"
}