Convalida acquisizione in streaming
L’acquisizione in streaming ti consente di caricare i dati in Adobe Experience Platform utilizzando endpoint di streaming in tempo reale. Le API di acquisizione in streaming supportano due modalità di convalida, sincrona e asincrona.
Introduzione
Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:
- Experience Data Model (XDM) System: il quadro standardizzato mediante il quale Experience Platform organizza i dati sull’esperienza del cliente.
- Streaming Ingestion: uno dei metodi con cui i dati possono essere inviati a 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 il 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 esempi di chiamate API nel Experience Platform guida alla risoluzione dei problemi.
Raccogli i valori per le intestazioni richieste
Per effettuare chiamate a Platform , devi prima completare le tutorial sull’autenticazione. Il completamento del tutorial sull’autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte Experience Platform Chiamate API, come mostrato di seguito:
- Autorizzazione: Bearer
{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 specifiche sandbox virtuali. Tutte le richieste a Platform Le API richiedono un’intestazione che specifichi il nome della sandbox in cui verrà eseguita l’operazione:
- x-sandbox-name:
{SANDBOX_NAME}
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:
- Content-Type:
application/json
Copertura di 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 sul motivo per cui un’acquisizione non è riuscita. Tuttavia, in caso di errore, i record che non superano la 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 sia del risultato della convalida XDM che, se questa non è riuscita, del motivo dell’errore.
Per impostazione predefinita, la convalida sincrona non è attivata. Per abilitarlo, devi passare il parametro di query opzionale syncValidation=true
quando si effettuano chiamate API. Inoltre, la convalida sincrona è attualmente disponibile solo se l'endpoint di flusso si trova nel data center VA7.
syncValidation
il parametro query è disponibile solo per il singolo endpoint di messaggio 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.
Formato API
POST /collection/{CONNECTION_ID}?syncValidation=true
{CONNECTION_ID}
id
valore della connessione streaming creata in precedenza.Richiesta
Invia la seguente richiesta per acquisire i dati all’ingresso dei dati con convalida sincrona:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{JSON_PAYLOAD}
Risposta
Con la convalida sincrona abilitata, una risposta corretta include eventuali errori di convalida riscontrati nel relativo 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 precedente elenca quante violazioni dello schema sono state trovate e quali sono state. Ad esempio, questa risposta indica che le chiavi workEmail
e person
non sono state definite nello schema e pertanto non sono consentite. Inoltre, contrassegna il valore per _id
come errato, poiché nello schema era previsto un string
, ma un long
è stato inserito. Una volta riscontrati cinque errori, il servizio di convalida stop elaborazione del messaggio. Tuttavia, altri messaggi continueranno a essere analizzati.
Convalida asincrona
La convalida asincrona è un metodo di convalida che non fornisce feedback immediati. I dati vengono invece inviati a un batch non riuscito in Data Lake per evitare la perdita di dati. Questi dati non riusciti possono essere recuperati in seguito per ulteriori analisi e ripetizioni. 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}
{CONNECTION_ID}
id
valore della connessione streaming creata in precedenza.Richiesta
Invia la seguente richiesta per acquisire i dati all’ingresso dei dati con convalida asincrona:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
{JSON_PAYLOAD}
Risposta
Se 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.