Convalida dell’acquisizione in streaming

L’acquisizione in streaming ti consente di caricare i dati in Adobe Experience Platform utilizzando gli endpoint di streaming in tempo reale. Le API Streaming Ingestion supportano due modalità di convalida, sincrone e asincrona.

Introduzione

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

Lettura di chiamate API di esempio

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

Raccogli i valori delle intestazioni richieste

Per effettuare chiamate a Platform API, devi prima completare l’ esercitazione sull'autenticazione. Il completamento dell’esercitazione sull’autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le Experience Platform Chiamate API, come mostrato di seguito:

  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Tutte le risorse in Experience Platform, compresi quelli appartenenti al Schema Registry, sono isolate in sandbox virtuali specifiche. Tutte le richieste a Platform Le API richiedono un’intestazione che specifichi il nome della sandbox in cui avrà luogo l’operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Per ulteriori informazioni sulle sandbox in Platform, vedi documentazione panoramica su sandbox.

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

  • Content-Type: application/json

Copertura della convalida

Streaming Validation Service riguarda la convalida nei seguenti settori:

  • Range
  • Presenza
  • Enum
  • Pattern
  • Tipo
  • Formato

Convalida sincrona

La convalida sincrona è un metodo di convalida che fornisce un feedback immediato sui motivi per cui un’acquisizione non è riuscita. Tuttavia, in caso di errore, i record con errore di convalida vengono eliminati e non possono essere inviati a valle. Di conseguenza, la convalida sincrona deve essere utilizzata solo durante il processo di sviluppo. Durante la convalida sincrona, i chiamanti vengono informati del risultato della convalida XDM e, in caso di errore, del motivo dell’errore.

Per impostazione predefinita, la convalida sincrona non è attivata. Per abilitarlo, devi trasmettere il parametro di query facoltativo. syncValidation=true quando effettui chiamate API. Inoltre, la convalida sincrona è attualmente disponibile solo se l'endpoint del flusso si trova nel data center VA7.

NOTA

La syncValidation il parametro query è disponibile solo per l'endpoint con messaggio singolo e non può essere utilizzato per l'endpoint batch.

Se un messaggio non riesce durante la convalida sincrona, non verrà scritto nella coda di output, che fornisce un feedback immediato agli utenti.

NOTA

Le modifiche allo schema potrebbero non essere immediatamente disponibili in quanto le modifiche sono memorizzate nella cache. Consenti fino a quindici minuti per l'aggiornamento della cache.

Formato API

POST /collection/{CONNECTION_ID}?syncValidation=true
Parametro Descrizione
{CONNECTION_ID} La id valore della connessione in streaming creata in precedenza.

Richiesta

Invia la seguente richiesta per l’acquisizione di dati all’entrata dati con convalida sincrona:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'
Parametro Descrizione
{JSON_PAYLOAD} Il corpo JSON di un dato che desideri acquisire.

Risposta

Con la convalida sincrona abilitata, una risposta corretta include eventuali errori di convalida riscontrati nel payload:

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [6aca7aa2d87ebd6b2780ca5724d94324a14475f140a2b69373dd5c714430dfd4] imsOrgId: [7BF122A65C5B3FE40A494026@AdobeOrg] Message is invalid",
        "cause": {
            "_streamingValidation": [
                {
                    "schemaLocation": "#",
                    "pointerToViolation": "#",
                    "causingExceptions": [
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [workEmail] is not permitted"
                        },
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [person] is not permitted"
                        },
                        {
                            "schemaLocation": "#/properties/_id",
                            "pointerToViolation": "#/_id",
                            "causingExceptions": [],
                            "keyword": "type",
                            "message": "expected type: String, found: Long"
                        }
                    ],
                    "message": "3 schema violations found"
                }
            ]
        }
    }
}

La risposta di cui sopra elenca quante violazioni dello schema sono state trovate e quali sono state riscontrate. Ad esempio, questa risposta indica che le chiavi workEmail e person non sono stati definiti nello schema e pertanto non sono consentiti. Inoltre, contrassegna il valore per _id non corretto, poiché lo schema prevedeva un string, ma long è stato invece inserito. Una volta riscontrati cinque errori, il servizio di convalida stop elaborazione del messaggio. Tuttavia, altri messaggi continueranno ad essere analizzati.

Convalida asincrona

La convalida asincrona è un metodo di convalida che non fornisce feedback immediato. I dati vengono invece inviati a un batch con errore in Data Lake per evitare la perdita di dati. Questi dati non riusciti possono essere recuperati in un secondo momento per un’ulteriore analisi e ripetizione. Questo metodo deve essere utilizzato nella produzione. Se non diversamente richiesto, l’acquisizione in streaming funziona in modalità di convalida asincrona.

Formato API

POST /collection/{CONNECTION_ID}
Parametro Descrizione
{CONNECTION_ID} La id valore della connessione in streaming creata in precedenza.

Richiesta

Invia la seguente richiesta per inserire i dati nell’entrata dati con convalida asincrona:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'
Parametro Descrizione
{JSON_PAYLOAD} Il corpo JSON di un dato che desideri acquisire.
NOTA

Non è richiesto alcun parametro di query aggiuntivo, in quanto la convalida asincrona è abilitata per impostazione predefinita.

Risposta

Con la convalida asincrona abilitata, una risposta corretta restituisce quanto segue:

{
    "inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
    "xactionId": "1555445493896:8600:8",
    "receivedTimeMs": 1555445493932,
    "syncValidation": {
        "skipped": true
    }
}

La risposta indica che la convalida sincrona è stata ignorata, in quanto non è stata esplicitamente richiesta.

Appendice

Questa sezione contiene informazioni sul significato dei vari codici di stato per le risposte per l’acquisizione dei dati.

Codici di stato

Codice di stato Che cosa significa
200 Operazione riuscita. Per la convalida sincrona, significa che ha superato i controlli di convalida. Per la convalida asincrona, significa che ha ricevuto il messaggio solo correttamente. Gli utenti possono scoprire l’eventuale stato del messaggio osservando il set di dati.
400 Errore. C'è qualcosa che non va nella tua richiesta. Un messaggio di errore con ulteriori dettagli viene ricevuto da Servizi di convalida in streaming.
401 Errore. La richiesta non è autorizzata. Sarà necessario richiedere un token portatore. Per ulteriori informazioni su come richiedere l’accesso, consulta questo tutorial o post di blog.
500 Errore. Errore interno del sistema.
501 Errore. Ciò significa che la convalida sincrona è not supportato per questa posizione.
503 Errore. Il servizio non è al momento disponibile. I clienti devono riprovare almeno tre volte utilizzando una strategia di back-off esponenziale.

In questa pagina