Recupero di batch non riusciti tramite l’API di accesso ai dati

Adobe Experience Platform fornisce due metodi per caricare e acquisire i dati. È possibile utilizzare l'acquisizione in batch, che consente di inserire i dati utilizzando vari tipi di file (ad esempio CSV), oppure l'acquisizione in streaming, che consente di inserire i dati in Platform utilizzando endpoint di streaming in tempo reale.

Questo tutorial descrive i passaggi necessari per recuperare informazioni su un batch non riuscito utilizzando le API Data Ingestion.

Introduzione

Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:

Lettura delle chiamate API di esempio

Questo tutorial 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 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 chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform.

Raccogliere i valori per le intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l'esercitazione di 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, incluse quelle appartenenti a Schema Registry, sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:

Batch campione non riuscito

Questa esercitazione utilizzerà dati di esempio con un timestamp formattato in modo errato che imposta il valore del mese su 00, come illustrato di seguito:

{
    "body": {
        "xdmEntity": {
            "id": "c8d11988-6b56-4571-a123-b6ce74236036",
            "timestamp": "2018-00-10T22:07:56Z",
            "environment": {
                "browserDetails": {
                    "userAgent": "Mozilla\/5.0 (Windows NT 5.1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/29.0.1547.57 Safari\/537.36 OPR\/16.0.1196.62",
                    "acceptLanguage": "en-US",
                    "cookiesEnabled": true,
                    "javaScriptVersion": "1.6",
                    "javaEnabled": true
                },
                "colorDepth": 32,
                "viewportHeight": 799,
                "viewportWidth": 414
            }
        }
    }
}

Il payload riportato sopra non verrà convalidato correttamente in base allo schema XDM a causa della marca temporale non valida.

Recupera il batch non riuscito

Formato API

GET /batches/{BATCH_ID}/failed

Richiesta

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

{
    "data": [
        {
            "name": "_SUCCESS",
            "length": "0",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/{BATCH_ID}/failed?path=_SUCCESS"
                }
            }
        },
        {
            "name": "part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json",
            "length": "1800",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/{BATCH_ID}/failed?path=part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 2
    }
}

Con la risposta precedente, puoi vedere quali blocchi del batch hanno avuto esito positivo o negativo. Da questa risposta è possibile vedere che il file part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json contiene il batch non riuscito.

Scarica il batch non riuscito

Una volta individuato il file non riuscito nel batch, è possibile scaricare il file non riuscito e visualizzare il messaggio di errore.

Formato API

GET /batches/{BATCH_ID}/failed?path={FAILED_FILE}

Richiesta

La seguente richiesta ti consente di scaricare il file che presentava errori di acquisizione.

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path={FAILED_FILE}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Poiché il batch acquisito precedente aveva una data/ora non valida, verrà visualizzato il seguente errore di convalida.

{
    "_validationErrors": [
        {
            "causingExceptions": [],
            "keyword": "format",
            "message": "[2018-00-23T22:07:01Z] is not a valid date-time. Expected [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1-9}Z, yyyy-MM-dd'T'HH:mm:ss[+-]HH:mm, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,9}[+-]HH:mm]",
            "pointerToViolation": "#/timestamp",
            "schemaLocation": "#/properties/timestamp"
        }
    ]
}

Passaggi successivi

Dopo aver letto questa esercitazione, hai imparato a recuperare gli errori dai batch non riusciti. Per ulteriori informazioni sull'acquisizione batch, leggere la guida per gli sviluppatori sull'acquisizione batch. Per ulteriori informazioni sull'acquisizione in streaming, leggere l'esercitazione sulla creazione di una connessione in streaming.

Appendice

Questa sezione contiene informazioni su altri tipi di errori di acquisizione che possono verificarsi.

XDM formattato in modo errato

Come l’errore di marca temporale nel flusso di esempio precedente, questi errori sono dovuti a XDM formattato in modo errato. Questi messaggi di errore variano a seconda della natura del problema. Di conseguenza, non è possibile visualizzare alcun esempio di errore specifico.

ID organizzazione mancante o non valido

Questo errore viene visualizzato se l’ID organizzazione risulta mancante nel payload non è valido.

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [{INLET_ID}] imsOrgId: [{ORG_ID}@AdobeOrg] Message has an absent or wrong ims org in the header"
    }
}

Schema XDM mancante

Questo errore viene visualizzato se manca schemaRef per xdmMeta.

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [{INLET_ID}] imsOrgId: [{ORG_ID}@AdobeOrg] Message has unknown xdm format"
    }
}

Nome sorgente mancante

Questo errore viene visualizzato se source nell'intestazione manca il relativo name.

{
    "_errors":{
        "_streamingValidation": [
            {
                "message": "Payload header is missing Source Name"
            }
        ]
    }
}

Entità XDM mancante

Questo errore viene visualizzato se non è presente xdmEntity.

{
    "_validationErrors": [
        {
            "message": "Payload body is missing xdmEntity"
        }
    ]
}