Acquisizione batch parziale

L’acquisizione in batch parziale consente di acquisire dati contenenti errori, fino a una determinata soglia. Con questa funzionalità, gli utenti possono inserire correttamente in Adobe Experience Platform tutti i dati corretti, mentre tutti i dati errati vengono raggruppati in batch separatamente, insieme ai dettagli sul motivo per cui non sono validi.

Questo documento fornisce un’esercitazione per gestire l’acquisizione in blocco parziale.

Introduzione

Questo tutorial richiede una conoscenza operativa dei vari servizi Adobe Experience Platform coinvolti nell’acquisizione in blocco parziale. Prima di iniziare questo tutorial, consulta la documentazione dei seguenti servizi:

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per effettuare correttamente chiamate alle API Experience Platform.

Lettura delle chiamate API di esempio

Questa guida fornisce esempi di chiamate API per illustrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un codice JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere gli esempi di chiamate API nella guida alla risoluzione dei problemi di Experience Platform.

Raccogliere i valori per le intestazioni richieste

Per effettuare chiamate alle API di Experience Platform, prima è necessario completare il tutorial sull’autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Tutte le richieste alle API Experience Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:

Abilitare un batch per l’acquisizione in blocco parziale nell’API enable-api

Puoi creare un nuovo batch con l’acquisizione parziale abilitata.

Per creare un nuovo batch, segui i passaggi descritti nella guida per gli sviluppatori sull'acquisizione batch. Una volta raggiunto il passaggio Create batch, aggiungi il seguente campo nel corpo della richiesta:

{
    "enableErrorDiagnostics": true,
    "partialIngestionPercent": 5
}

Abilitare un batch per l’acquisizione in blocco parziale nell’interfaccia utente enable-ui

Per abilitare un batch per l'acquisizione parziale tramite l'interfaccia utente Experience Platform, è possibile creare un nuovo batch tramite le connessioni di origine, creare un nuovo batch in un set di dati esistente o creare un nuovo batch tramite "Map CSV to XDM flow".

Crea una nuova connessione sorgente new-source

Per creare una nuova connessione di origine, seguire i passaggi elencati nella Panoramica origini. Una volta raggiunto il passaggio Dataflow detail, prendere nota dei campi Partial ingestion e Error diagnostics.

L'interruttore Partial ingestion consente di abilitare o disabilitare l'utilizzo dell'acquisizione batch parziale.

L'interruttore Error diagnostics viene visualizzato solo quando l'interruttore Partial ingestion è disattivato. Questa funzione consente a Experience Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l'interruttore Partial ingestion è attivato, la diagnostica avanzata degli errori viene applicata automaticamente.

Error threshold consente di impostare la percentuale di errori accettabili prima che l'intero batch abbia esito negativo. Per impostazione predefinita, questo valore è impostato su 5%.

Usa un set di dati esistente existing-dataset

Per utilizzare un set di dati esistente, inizia selezionandone uno. La barra laterale a destra contiene informazioni sul set di dati.

L'interruttore Partial ingestion consente di abilitare o disabilitare l'utilizzo dell'acquisizione batch parziale.

L'interruttore Error diagnostics viene visualizzato solo quando l'interruttore Partial ingestion è disattivato. Questa funzione consente a Experience Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l'interruttore Partial ingestion è attivato, la diagnostica avanzata degli errori viene applicata automaticamente.

Error threshold consente di impostare la percentuale di errori accettabili prima che l'intero batch abbia esito negativo. Per impostazione predefinita, questo valore è impostato su 5%.

Ora puoi caricare i dati utilizzando il pulsante Aggiungi dati, che verrà acquisito tramite l'acquisizione parziale.

Utilizza il flusso "Map CSV to XDM schema" map-flow

Per utilizzare il flusso "Map CSV to XDM schema", segui i passaggi elencati nell'esercitazione Mappare un file CSV. Una volta raggiunto il passaggio Add data, prendere nota dei campi Partial ingestion e Error diagnostics.

L'interruttore Partial ingestion consente di abilitare o disabilitare l'utilizzo dell'acquisizione batch parziale.

L'interruttore Error diagnostics viene visualizzato solo quando l'interruttore Partial ingestion è disattivato. Questa funzione consente a Experience Platform di generare messaggi di errore dettagliati sui batch acquisiti. Se l'interruttore Partial ingestion è attivato, la diagnostica avanzata degli errori viene applicata automaticamente.

Error threshold consente di impostare la percentuale di errori accettabili prima che l'intero batch abbia esito negativo. Per impostazione predefinita, questo valore è impostato su 5%.

Abilitare l’acquisizione parziale e la diagnostica degli errori per un flusso di dati esistente

Se un flusso di dati in Experience Platform è stato creato senza abilitare l’acquisizione parziale o la diagnostica degli errori, puoi comunque abilitare queste funzioni senza ricreare il flusso. Abilitando l’acquisizione parziale e una diagnostica affidabile degli errori, puoi migliorare notevolmente l’affidabilità e la facilità di risoluzione dei problemi nei flussi di lavoro di acquisizione dei dati. Leggi le sezioni seguenti per scoprire come abilitare l'acquisizione parziale e la diagnostica degli errori per un flusso di dati esistente utilizzando l'API Flow Service.

Per impostazione predefinita, nei flussi di dati potrebbe non essere abilitata l’acquisizione parziale o la diagnostica degli errori. Queste funzioni sono utili per identificare e isolare i problemi durante l’acquisizione dei dati. Utilizzando l'API Flow Service, puoi recuperare la configurazione del flusso di dati corrente e applicare le modifiche necessarie utilizzando una richiesta PATCH.

Segui i passaggi seguenti per abilitare l’acquisizione parziale e la diagnostica degli errori per un flusso di dati esistente.

Recuperare i dettagli del flusso

Per recuperare le configurazioni del flusso di dati, effettua una richiesta GET all'endpoint /flows/{FLOW_ID} e fornisci l'ID del flusso di dati. Per ulteriori informazioni sul recupero dei dettagli del flusso di dati, consulta la Guida all'aggiornamento dei flussi di dati Flow Service API.

Assicurarsi di salvare il valore del campo etag restituito nella risposta. Questo è necessario affinché la richiesta di aggiornamento garantisca la coerenza della versione.

Configurazione del flusso di aggiornamento

Quindi, effettua una richiesta PATCH all'endpoint /flows/ e fornisci l'ID del flusso di dati per cui desideri abilitare l'acquisizione parziale e la diagnostica degli errori.

Formato API

PATCH /flows/{FLOW_ID}

Richiesta

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'
    -H 'If-Match: "1a0037e4-0000-0200-0000-602e06f60000"' \
    -d '[
        {
            "op": "add",
            "path": "/options",
            "value": {
                "partialIngestionPercent": "10"
            }
        },
        {
            "op": "add",
            "path": "/options/errorDiagnosticsEnabled",
            "value": true
        }
    ]'

Risposta

In caso di esito positivo, la risposta restituisce id del flusso di dati e etag aggiornato.

{
    "id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
    "etag": "\"2c000802-0000-0200-0000-613976440000\""
}

Verifica l’aggiornamento

Una volta completato PATCH, effettua una richiesta GET e recupera il flusso di dati per verificare che le modifiche siano state completate correttamente.

Formato API

GET /flows/{FLOW_ID}

Richiesta

La richiesta seguente recupera informazioni aggiornate relative all’ID flusso.

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/2edc08ac-4df5-4fe6-936f-81a19ce92f5c' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli del flusso di dati, confermando che l’acquisizione parziale e la diagnostica degli errori sono ora abilitate nella sezione options.

"options": {
    "partialIngestionPercent": 10,
    "errorDiagnosticsEnabled": true
}

Passaggi successivi next-steps

Questa esercitazione illustra come creare o modificare un set di dati per abilitare l’acquisizione in blocco parziale. Per ulteriori informazioni sull'acquisizione batch, consulta la guida per gli sviluppatori sull'acquisizione batch.

Per informazioni sul monitoraggio degli errori di acquisizione parziale, leggere la guida alla diagnostica degli errori di acquisizione batch.