Origini dati esterne

Le origini dati esterne consentono di definire una connessione a sistemi di terze parti, ad esempio è in uso un sistema di prenotazione alberghiera per verificare se il cliente ha registrato una stanza. Al posto 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:

1. Dall’elenco delle origini dati, fai clic su Crea origine dati per creare una nuova origine dati esterna.

   

   Sul lato destro dello schermo si apre il riquadro di configurazione dell’origine dati .

   

2. Inserisci un nome per l’origine dati.

   NOTA

   Non utilizzare spazi o caratteri speciali. Non usare più di 30 caratteri.

3. Aggiungi una descrizione all’origine dati. Questo passaggio è facoltativo.

4. Aggiungi l’URL del servizio esterno. Nel nostro esempio: https://api.adobeweather.org/weather.

   ATTENZIONE

   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.

   

5. Configura l’autenticazione in base alla configurazione del servizio esterno: Nessuna autenticazione, Base, Personalizzato o Chiave API. Per ulteriori informazioni sulla modalità di autenticazione personalizzata, vedi questa sezione. Le scelte del nostro esempio:

   • Tipo: "Chiave API"
   • Nome: "appid" (nome del parametro della chiave API)
   • Valore: "1234" (questo è il valore della nostra chiave API)
   • Posizione: "Query parameter" (la chiave API si trova nell’URL)

   

6. Aggiungi un nuovo gruppo di campi per ciascun set di parametri API facendo clic su Aggiungi un nuovo gruppo di campi. 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:

• Utilizzato in: visualizza il numero di percorsi che utilizzano un gruppo di campi. Puoi fare clic su 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: fai clic all’interno del 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. Puoi fare clic su Incolla un nuovo payload per 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.

Nel caso di una chiamata di GET che richieda i parametri, immetti i parametri nel Valori dinamici e vengono aggiunti automaticamente alla fine della chiamata . Nel caso di una chiamata POST, è necessario:

• elencare i parametri da trasmettere al momento della chiamata nel Valori dinamici (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:

  {"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

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:

1. Chiama l’endpoint per generare il token di accesso.
2. 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 così come sono: key1=value1&key2=value2&…
  • 'json': significa che il tipo di contenuto sarà application/json (charset UTF-8) e che le coppie chiave-valore saranno serializzate come oggetto json così come sono: { "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.

Ecco un esempio per il tipo di autenticazione portatore:

{
  "authentication": {
    "type": "customAuthorization",
    "authorizationType": "Bearer",
    "endpoint": "http://localhost:${port}/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"
    }
  }
}

Ecco 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"
}

Ecco un esempio della risposta della chiamata API di accesso:

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S"
}

Risorse Business.Adobe.com