Origini dati esterne concept_t2s_kqt_52b
Le origini dati esterne consentono di definire una connessione a sistemi di terze parti, ad esempio se si utilizza un sistema di prenotazione alberghiera per verificare se un cliente ha registrato una stanza. A differenza dell’origine dati integrata di Adobe Experience Platform, puoi creare un numero illimitato di origini dati esterne.
Sono supportate le API REST basate su POST o GET e che restituiscono JSON. Sono supportate le modalità chiave API, sia l’autenticazione di base che personalizzata.
Prendiamo l’esempio di un servizio API meteorologico che intendo sfruttare per personalizzare i comportamenti del mio percorso secondo i dati meteo in tempo reale.
Di seguito sono riportati due esempi della chiamata API:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
La chiamata è composta da un URL principale, https://api.adobeweather.org/weather, due set di parametri ("city" per la città e "lat/long" per la latitudine e la longitudine) e la chiave API (appid).
Di seguito sono riportati i passaggi principali per la creazione e la configurazione di una nuova origine dati esterna:
-
Nell'elenco delle origini dati fare clic su Create data source per creare una nuova origine dati esterna.
Sul lato destro dello schermo si apre il riquadro di configurazione dell’origine dati .
-
Inserisci un nome per l’origine dati.
note note NOTE Non utilizzare spazi o caratteri speciali. Non usare più di 30 caratteri. -
Aggiungi una descrizione all’origine dati. Questo passaggio è facoltativo.
-
Aggiungi l’URL del servizio esterno. Nel nostro esempio: https://api.adobeweather.org/weather.
note caution CAUTION Per motivi di sicurezza, è consigliabile utilizzare HTTPS. Inoltre, non consentiamo l’uso di indirizzi Adobe che non siano disponibili al pubblico, né di indirizzi IP. 
-
Imposta l’autenticazione in base alla configurazione del servizio esterno: No authentication, Basic, Custom o API key. Per ulteriori informazioni sulla modalità di autenticazione personalizzata, vedere questa sezione. Le scelte del nostro esempio:
- Type: "API key"
- Value: "1234" (questo è il valore della nostra chiave API)
- Name: "appid" (nome del parametro della chiave API)
- Location: "Query parameter" (la chiave API si trova nell’URL)
-
Per aggiungere un nuovo gruppo di campi per ciascun set di parametri API, fai clic su Add a New Field Group. Non utilizzare spazi o caratteri speciali nel nome del gruppo di campi. Nel nostro esempio, dobbiamo creare due gruppi di campi, uno per ciascun insieme di parametri (city e long/lat).
Per il set di parametri "long/lat", viene creato un gruppo di campi con le seguenti informazioni:
- Used in: visualizza il numero di percorsi che utilizzano un gruppo di campi. Puoi fare clic sull’icona View journeys per visualizzare l’elenco dei percorsi che utilizzano questo gruppo di campi.
- Method: seleziona il metodo POST o GET. Nel nostro caso, scegliamo il metodo GET.
- Response Payload: fai clic all’interno del campo Payload e incolla un esempio del payload restituito dalla chiamata. Per il nostro esempio, abbiamo utilizzato un payload trovato su un sito web API per il meteo. Verifica la correttezza dei tipi di campi. Ogni volta che viene chiamata l’API, il sistema recupererà tutti i campi inclusi nell’esempio di payload. Se vuoi modificare il payload attualmente trasmesso, è possibile fare clic su Paste a new payload.
- Dynamic Values: inserisci i diversi parametri separati da una virgola, nel nostro esempio "long,lat". Poiché i valori del parametro dipendono dal contesto di esecuzione, saranno definiti all’interno dei percorsi. Consulta questa pagina.
- Sent Payload: questo campo non viene visualizzato nel nostro esempio. È disponibile solo se si seleziona il metodo POST. Incolla il payload che verrà inviato al sistema di terze parti.
In presenza di una chiamata GET che richieda i parametri, inseriscili nel campo Dynamic Values e verranno aggiunti automaticamente alla fine della chiamata. Nel caso di una chiamata POST, è necessario:
-
Elencare i parametri da trasmettere al momento della chiamata nel campo Dynamic Values, nell’esempio seguente: "identifier".
-
Specificare i parametri anche utilizzando la medesima sintassi nel corpo del payload inviato. A tale scopo, è necessario aggiungere: "param": “nome del tuo parametro”, nell’esempio seguente è "identifier". Attieniti alla sintassi seguente:
code language-none {"id":{"param":"identifier"}}
Fai clic su Save.
L’origine dati è ora configurata ed è pronta per essere utilizzata nei percorsi, ad esempio nelle tue condizioni o per personalizzare un’e-mail. Se la temperatura è superiore a 30°C, puoi decidere di inviare una comunicazione specifica.
Modalità di autenticazione personalizzata section_wjp_nl5_nhb
Questa modalità di autenticazione viene utilizzata per la tipologia complessa, spesso impiegata per la chiamata dei protocolli di wrapping API come OAuth2 e per il recupero di un token di accesso da inserire nella richiesta HTTP effettiva per l’azione.
Quando configuri l’autenticazione personalizzata, puoi fare clic sul pulsante seguente per verificare la corretta configurazione del payload di autenticazione personalizzata.
Se il test ha esito positivo, il pulsante diventa verde.
Con questa autenticazione, l’esecuzione dell’azione è un processo suddiviso in due fasi:
- Chiama l’endpoint per generare il token di accesso.
- Chiama l’API REST inserendo il token di accesso nel modo appropriato.
Questa autenticazione è costituita da due parti.
Definizione dell’endpoint da chiamare per la generazione del token di accesso:
-
endpoint: URL da utilizzare per generare l’endpoint
-
metodo della richiesta HTTP sull’endpoint (GET o POST)
-
intestazioni: coppie chiave/valore da inserire come intestazioni in questa chiamata, se necessario
-
corpo: descrive il corpo della chiamata se il metodo è POST. Supportiamo una struttura del corpo limitata, definita in bodyParams (coppie chiave/valore). Il bodyType descrive il formato e la codifica del corpo nella chiamata:
- 'form': significa che il tipo di contenuto sarà application/x-www-form-urlencoded (charset UTF-8) e che le coppie chiave/valore saranno serializzate come segue: key1=value1&key2=value2&…
- 'json': indica che il tipo di contenuto sarà application/json (charset UTF-8) e che le coppie di valori chiave saranno serializzate così come sono, come oggetto json: { "key1": "value1", "key2": "value2", …}
La definizione della modalità di inserimento del token di accesso nella richiesta HTTP dell’azione:
-
authorizationType: definisce il modo in cui il token di accesso generato deve essere inserito nella chiamata HTTP per l’azione. I valori possibili sono:
- bearer: indica che il token di accesso deve essere inserito nell’intestazione Autorizzazione, ad esempio: Authorization: Bearer <token di accesso>
- header: indica che il token di accesso deve essere inserito come intestazione, il nome dell’intestazione è definito dalla proprietà tokenTarget. Ad esempio, se tokenTarget è myHeader, il token di accesso verrà inserito come intestazione: myHeader: <token di accesso>
- queryParam: indica che il token di accesso deve essere inserito come queryParam, il nome del param di query è definito dalla proprietà tokenTarget. Ad esempio, se il tokenTarget è myQueryParam, l’URL della chiamata di azione sarà: <url>?myQueryParam=<token di accesso>
-
tokenInResponse: indica come estrarre il token di accesso dalla chiamata di autenticazione. Questa proprietà può corrispondere a:
- 'response': indica che la risposta HTTP è il token di accesso.
- Un selettore in un json: poiché la risposta deve essere un json, non sono supportati altri formati come XML. Il formato di questo selettore è json://<percorso della proprietà del token di accesso>. Ad esempio, se la risposta della chiamata è: { "access_token": "theToken", "timestamp": 12323445656}, tokenInResponse sarà: json: //access_token
Il formato di questa autenticazione è:
{
"type": "customAuthorization",
"authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
(optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
"endpoint": "<URL of the authentication endpoint>",
"method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
(optional) "headers": {
"<header name>": "<header value>",
...
},
(optional, mandatory if method is 'POST') "body": {
"bodyType": "<'form'or 'json'>,
"bodyParams": {
"param1": value1,
...
}
},
"tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'"
}
Adesso puoi modificare la durata della cache del token per un’origine dati di autenticazione personalizzata. Di seguito è riportato un esempio di payload di autenticazione personalizzato. La durata della cache è definita nel parametro “cacheDuration”. Tale parametro Specifica la durata di conservazione del token generato nella cache. L’unità può essere in millisecondi, secondi, minuti, ore, giorni, mesi, anni.
"authentication": {
"type":"customAuthorization",
"authorizationType":"Bearer",
"endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
"method":"POST",
"headers": {
"Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
},
"body": {
"bodyType":"form",
"bodyParams": {
"scope":"cn mail givenname uid employeeNumber",
"grant_type":"password",
"username":"${epsilonUserName}",
"password":"${epsilonUserPassword}"
}
},
"tokenInResponse":"json://access_token",
"cacheDuration":
{ "duration":5, "timeUnit":"seconds" }
}