L’assimilazione dello streaming consente di caricare i dati su Adobe Experience Platform utilizzando gli endpoint di streaming in tempo reale. Le API di assimilazione dello streaming supportano due modalità di convalida: sincrona e asincrona.
Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:
Questa esercitazione 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.
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:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Tutte le risorse in Experience Platform, comprese quelle appartenenti al gruppo Schema Registry, 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:
{SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Platform, consultate la documentazione sulla panoramica dellasandbox.
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva:
application/json
Streaming Validation Service copre la convalida nei seguenti settori:
La convalida sincrona è un metodo di convalida che fornisce un feedback immediato sui motivi per cui un'assimilazione non è riuscita. Tuttavia, in caso di errore, i record con errore di convalida vengono ignorati 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 attivarla, è necessario passare il parametro di query facoltativo synchronousValidation=true
quando si effettuano chiamate API. Inoltre, la convalida sincrona è attualmente disponibile solo se l'endpoint del flusso si trova nel centro dati VA7.
Se un messaggio ha esito negativo durante la convalida sincrona, il messaggio non verrà scritto nella coda di output, che fornisce agli utenti un feedback immediato.
Formato API
POST /collection/{CONNECTION_ID}?synchronousValidation=true
Parametro | Descrizione |
---|---|
{CONNECTION_ID} |
Il id valore della connessione di streaming creata in precedenza. |
Richiesta
Invia la seguente richiesta per l’inserimento di dati all’ingresso dati con convalida sincrona:
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?synchronousValidation=true \
-H "Content-Type: application/json" \
-d '{JSON_PAYLOAD}'
Parametro | Descrizione |
---|---|
{JSON_PAYLOAD} |
Il corpo JSON di un dato che desideri acquisire. |
Risposta
Quando la convalida sincrona è attivata, una risposta corretta include eventuali errori di convalida 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 riportata 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 state definite nello schema, pertanto non sono consentite. Inoltre, contrassegna il valore per _id
come errato, poiché lo schema prevedeva un string
, ma long
è stato inserito un valore. Si noti che, una volta riscontrati cinque errori, il servizio di convalida interrompe l'elaborazione del messaggio. Tuttavia, altri messaggi continueranno ad essere analizzati.
La convalida asincrona è un metodo di convalida che non fornisce feedback immediato. Al contrario, i dati vengono inviati a un batch con errore per Data Lake evitare la perdita di dati. Questi dati con errore possono essere successivamente recuperati per ulteriore analisi e ripetizione. Questo metodo deve essere utilizzato nella produzione. Se non diversamente richiesto, l'assimilazione in streaming viene eseguita in modalità di convalida asincrona.
Formato API
POST /collection/{CONNECTION_ID}
Parametro | Descrizione |
---|---|
{CONNECTION_ID} |
Il id valore della connessione di streaming creata in precedenza. |
Richiesta
Invia la seguente richiesta per l’inserimento di dati all’ingresso 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. |
Non è richiesto alcun parametro di query aggiuntivo, in quanto la convalida asincrona è abilitata per impostazione predefinita.
Risposta
Se la convalida asincrona è attivata, una risposta corretta restituisce quanto segue:
{
"inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
"xactionId": "1555445493896:8600:8",
"receivedTimeMs": 1555445493932,
"synchronousValidation": {
"skipped": true
}
}
Tenere presente che la risposta indica che la convalida sincrona è stata saltata, in quanto non è stata esplicitamente richiesta.
Questa sezione contiene informazioni sul significato dei vari codici di stato per le risposte per l’assimilazione dei dati.
Codice di stato | Significato |
---|---|
200 | Operazione riuscita. Per la convalida sincrona, significa che ha superato i controlli di convalida. Per la convalida asincrona, significa che ha ricevuto correttamente solo il messaggio. Gli utenti possono scoprire lo stato finale del messaggio osservando il dataset. |
400 | Errore. C'è qualcosa che non va con la tua richiesta. Un messaggio di errore con ulteriori dettagli viene ricevuto dai servizi di convalida in streaming. |
401 | Errore. La tua richiesta non è autorizzata. Dovrai richiedere un token per il portatore. Per ulteriori informazioni su come richiedere l'accesso, consultate questa esercitazione o questo post diblog. |
500 | Errore. Errore interno del sistema. |
501 | Errore. Ciò significa che la convalida sincrona non è supportata per questa posizione. |
503 | Errore. Il servizio non è al momento disponibile. I client devono riprovare almeno tre volte utilizzando una strategia di back-off esponenziale. |