Show Menu
ARGOMENTI×

Iniezione parziale del batch

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 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.

Introduzione

Questa esercitazione richiede una conoscenza approfondita dei diversi servizi di Adobe Experience Platform coinvolti nell'assimilazione parziale dei batch. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi:
  • Caricamento batch: Metodo che Platform raccoglie e memorizza i dati dai file di dati, come CSV e Parquet.
  • Experience Data Model (XDM) : Il framework standard con cui Platform organizzare i dati relativi all'esperienza del cliente.
Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per eseguire correttamente le chiamate alle Platform API.

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

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle Platform API, è prima necessario completare l'esercitazione sull' autenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate Experience Platform API, 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 avrà luogo l'operazione:
  • x-sandbox-name: {SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Platform, consultate la documentazione sulla panoramica della sandbox.

Abilitare un batch per l'assimilazione parziale dei batch nell'API

Questa sezione descrive come abilitare un batch per l'assimilazione parziale dei batch mediante l'API. Per istruzioni sull’utilizzo dell’interfaccia utente, leggete il passaggio Abilita batch per l’inserimento parziale dei batch nell’interfaccia utente .
Potete creare un nuovo batch con l’assimilazione parziale abilitata.
Per creare un nuovo batch, segui i passaggi descritti nella guida per gli sviluppatori per l’assimilazione batch. Una volta raggiunto il passaggio Crea batch , aggiungi il seguente campo nel corpo della richiesta:
{
    ...
    "enableErrorDiagnostics": true,
    "partialIngestionPercentage": 5
    ...
}

Proprietà
Descrizione
enableErrorDiagnostics
Flag che consente Platform di generare messaggi di errore dettagliati sul batch.
partialIngestionPercentage
Percentuale di errori accettabili prima che l'intero batch non riesca. Quindi, in questo esempio, un massimo del 5% del batch può essere costituito da errori, prima che venga meno.

Abilitare un batch per l’assimilazione parziale dei batch nell’interfaccia utente

Questa sezione descrive come abilitare un batch per l’assimilazione parziale dei batch utilizzando l’interfaccia utente. Se avete già attivato un batch per l'assimilazione parziale dei batch utilizzando l'API, potete passare alla sezione successiva.
Per abilitare un batch per l’assimilazione parziale nell’ Platform interfaccia utente, potete creare un nuovo batch tramite connessioni sorgente, creare un nuovo batch in un set di dati esistente o creare un nuovo batch tramite ilMap CSV to XDM flow".

Creare una nuova connessione di origine

Per creare una nuova connessione di origine, segui i passaggi elencati nella panoramica Panoramica sui connettori sorgente Origini. Una volta raggiunto il Dataflow detail passaggio, prendete nota dei Partial ingestion campi e Error diagnostics .
L’ Partial ingestion interruttore consente di attivare o disattivare l’inserimento parziale dei batch.
L' Error diagnostics interruttore viene visualizzato solo quando l' Partial ingestion interruttore è disattivato. Questa funzione consente Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l' Partial ingestion interruttore è attivato, la diagnostica degli errori avanzata viene applicata automaticamente.
Consente di Error threshold impostare la percentuale di errori accettabili prima che l'intero batch non riesca. Per impostazione predefinita, questo valore è impostato su 5%.

Utilizzare un dataset esistente

Per utilizzare un set di dati esistente, iniziare selezionando un set di dati. La barra laterale a destra include informazioni sul set di dati.
L’ Partial ingestion interruttore consente di attivare o disattivare l’inserimento parziale dei batch.
L' Error diagnostics interruttore viene visualizzato solo quando l' Partial ingestion interruttore è disattivato. Questa funzione consente Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l' Partial ingestion interruttore è attivato, la diagnostica degli errori avanzata viene applicata automaticamente.
Consente di Error threshold impostare la percentuale di errori accettabili prima che l'intero batch non riesca. Per impostazione predefinita, questo valore è impostato su 5%.
Ora puoi caricare i dati tramite il pulsante Aggiungi dati e li assimilerai parzialmente.

Utilizzare il flusso "Map CSV to XDM schema"

Per usare il flussoMap CSV to XDM schema"di prova", segui i passaggi elencati nell’esercitazione Mappa un file CSV . Una volta raggiunto il Add data passaggio, prendete nota dei Partial ingestion campi e Error diagnostics .
L’ Partial ingestion interruttore consente di attivare o disattivare l’inserimento parziale dei batch.
L' Error diagnostics interruttore viene visualizzato solo quando l' Partial ingestion interruttore è disattivato. Questa funzione consente Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l' Partial ingestion interruttore è attivato, la diagnostica degli errori avanzata viene applicata automaticamente.
Consente di Error threshold impostare la percentuale di errori accettabili prima che l'intero batch non riesca. Per impostazione predefinita, questo valore è impostato su 5%.

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 di 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": {
            ...
            "acp_enableErrorDiagnostics": true,
            "acp_partialIngestionPercent": 5
            ...
        },
        "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"
}