Origini dati esterne

Ultimo aggiornamento: 2024-02-22
  • Argomenti:
  • Journeys
    Visualizza ulteriori informazioni su questo argomento
  • Data Sources
    Visualizza ulteriori informazioni su questo argomento
  • Integrations
    Visualizza ulteriori informazioni su questo argomento
  • Creato per:
  • Intermediate
    Experienced
    Developer
    Admin

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.

NOTA

I guardrail quando si lavora con sistemi esterni sono elencati in questa pagina.

NOTA

Poiché le risposte sono ora supportate, per i casi d’uso relativi a origini dati esterne devi utilizzare azioni personalizzate anziché origini dati.

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 la modalità di autenticazione di base, devi inserire un nome utente e una password.

    NOTA

    Quando viene eseguita la chiamata di autenticazione, il <username>:<password> stringa, codificata in base64, viene aggiunta nell’intestazione Authentication.

    Per ulteriori informazioni sulla modalità di autenticazione personalizzata, consulta questa sezione. Nel nostro esempio, scegliamo la modalità di autenticazione della chiave API:

    • Tipo: "API key"
    • 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. Per aggiungere un nuovo gruppo di campi per ciascun set di parametri API, fai 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: seleziona 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 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 nella 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 nella 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:

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

Questa autenticazione è costituita da due parti.

Definizione dell’endpoint da chiamare per generare il 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': 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

  • 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://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"
    }
  }
}
NOTA

Il token di autenticazione viene memorizzato nella cache al percorso: se due percorsi utilizzano la stessa azione personalizzata, ogni percorso ha un proprio token memorizzato nella cache. Il token non è condiviso tra questi percorsi.

La durata della cache consente di evitare un numero eccessivo di chiamate agli endpoint di autenticazione. La conservazione dei token di autenticazione è memorizzata nella cache dei servizi, non vi è persistenza. Se un servizio viene riavviato, inizia con una cache pulita. Per impostazione predefinita, la durata della cache è di 1 ora. Nel payload di autenticazione personalizzata, può essere adattato specificando un’altra durata di conservazione.

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
}

In questa pagina