Origini dati esterne external-data-sources
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 Crea Source dati 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 Sono consentiti solo caratteri alfanumerici e trattini bassi. La lunghezza massima è 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. 
-
Configura l'autenticazione in base alla configurazione del servizio esterno: Nessuna autenticazione, Base, Personalizzata o Chiave API.
Per la modalità di autenticazione di base, devi inserire un nome utente e una password.
note note NOTE Quando viene eseguita la chiamata di autenticazione, la stringa <username>:<password>, codificata in base64, viene aggiunta nell'intestazione Autenticazione.Per ulteriori informazioni sulla modalità di autenticazione personalizzata, vedere questa sezione. Nel nostro esempio, scegliamo la modalità di autenticazione della chiave API:
- Tipo: "Chiave API"
- Nome: "appid" (nome del parametro della chiave API)
- Valore: "1234" (questo è il valore della nostra chiave API)
- Posizione: "Parametro query" (la chiave API si trova nell'URL)
-
Aggiungere un nuovo gruppo di campi per ogni set di parametri API facendo clic su Aggiungi un nuovo gruppo di campi. Nel nome del gruppo di campi sono consentiti solo caratteri alfanumerici e trattini bassi. La lunghezza massima è di 30 caratteri. 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:
-
Utilizzato in: visualizza il numero di percorsi che utilizzano un gruppo di campi. È possibile fare clic sull'icona Visualizza percorsi per visualizzare l'elenco dei percorsi che utilizzano questo gruppo di campi.
-
Metodo: selezionare il metodo POST o GET. Nel nostro caso, scegliamo il metodo GET.
-
Valori dinamici: 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. Ulteriori informazioni
-
Payload di risposta: fare clic all'interno del campo Payload e incollare 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. Puoi fare clic su Incolla un nuovo payload se desideri modificare il payload attualmente trasmesso.
-
Payload inviato: 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 caso di una chiamata di GET che richieda i parametri, inseriscili nel campo Valori dinamici e verranno aggiunti automaticamente alla fine della chiamata. Nel caso di una chiamata POST, è necessario:
-
Elencare i parametri da passare al momento della chiamata nel campo Valori dinamici (nell'esempio seguente: "identifier").
-
Specificare i parametri anche utilizzando la medesima sintassi nel corpo del payload inviato. A questo scopo, devi aggiungere: "param": "nome del tuo parametro" (nell’esempio seguente: "identifier"). Attieniti alla sintassi seguente:
code language-none {"id":{"param":"identifier"}}
Fai clic su Salva.
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 custom-authentication-mode
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.
Definizione dell’endpoint da chiamare per generare il token di accesso custom-authentication-endpoint
-
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': indica che il tipo di contenuto sarà application/x-www-form-urlencoded (charset UTF-8) e che le coppie chiave-valore saranno serializzate così come sono: key1=value1&key2=value2&…
- 'json': indica che il tipo di contenuto sarà application/json (charset UTF-8) e che le coppie chiave-valore saranno serializzate così come sono, come oggetto json: { "key1": "value1", "key2": "value2", …}
Definizione del modo in cui il token di accesso deve essere inserito nella richiesta HTTP dell’azione custom-authentication-access-token
-
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",
"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>'",
"cacheDuration": {
(optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
(optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
"timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
},
"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'>",
}
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.
Ecco un esempio per il tipo di autenticazione bearer:
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
}
}
}
Di seguito è riportato un esempio per il tipo di autenticazione dell’intestazione:
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
}
}
Ecco un esempio della risposta della chiamata API di accesso:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}