Les sources de données externes vous permettent de définir une connexion à des systèmes tiers ; par exemple, si vous utilisez un système de réservation d’hôtels pour vérifier si la personne a réservé une chambre. Contrairement à la source de données Adobe Experience Platform intégrée, vous pouvez créer autant de sources de données externes que nécessaire.
Les mécanismes de sécurisation lorsque vous utilisez des systèmes externes sont répertoriés dans cette page.
Les API REST utilisant POST ou GET et renvoyant JSON sont prises en charge. Les modes d’authentification simple, personnalisé et par clé API sont pris en charge.
Prenons l’exemple d’un service API météorologique que je souhaite utiliser pour personnaliser les comportements de mon parcours en fonction des données météorologiques en temps réel.
Voici deux exemples de l’appel API :
L’appel est composé d’une URL principale (https://api.adobeweather.org/weather), de deux jeux de paramètres (« city » pour la ville et « lat/long » pour la latitude et la longitude) et de la clé API (appid).
Les principales étapes nécessaires pour créer et configurer une source de données externe sont les suivantes :
Dans la liste des sources de données, cliquez sur Créer une source de données pour créer une source de données externe.
Le volet de configuration de la source de données s’ouvre alors dans la partie droite de l’écran.
Attribuez un nom à votre source de données.
N'utilisez ni espaces ni caractères spéciaux. Utilisez 30 caractères au maximum.
Ajoutez une description à la source de données. Cette étape est facultative.
Ajoutez l'URL du service externe. Dans notre exemple : https://api.adobeweather.org/weather.
Nous vous recommandons vivement d'utiliser le protocole HTTPS pour des raisons de sécurité. Notez également que l’utilisation des adresses Adobe qui ne sont pas publiques et des adresses IP n’est pas autorisée.
Configurez l’authentification en fonction de la configuration du service externe : Aucune authentification, Simple, Personnalisé ou Clé API. Pour plus d’informations sur le mode d’authentification personnalisée, reportez-vous à cette section. Dans cet exemple, nous allons effectuer les choix suivants :
Ajoutez un nouveau groupe de champs pour chaque jeu de paramètres d’API en cliquant sur Ajouter un nouveau groupe de champs. N’utilisez ni espaces ni caractères spéciaux dans le nom du groupe de champs. Dans cet exemple, nous devons créer deux groupes de champs, un pour chaque jeu de paramètres (city et long/lat).
Pour le jeu de paramètres « long/lat », nous créons un groupe de champs avec les informations suivantes :
Utilisé(e) dans : affiche le nombre de parcours qui utilisent un groupe de champs. Vous pouvez cliquer sur l’icône Afficher les parcours pour faire apparaître la liste des parcours utilisant ce groupe de champs.
Méthode : sélectionnez la méthode POST ou GET. Dans notre exemple, nous choisissons la méthode GET.
Valeurs dynamiques : saisissez les différents paramètres, séparés par une virgule (« long,lat » dans notre exemple). Étant donné que les valeurs des paramètres dépendent du contexte d’exécution, elles sont définies dans les parcours. En savoir plus
Payload en réponse : cliquez dans le champ Payload et collez un exemple de la payload renvoyée par l’appel. Dans cet exemple, nous avons utilisé une payload trouvée sur un site web d’API météo. Vérifiez que les types de champs sont corrects. À chaque appel de l’API, le système récupère tous les champs contenus dans l’exemple de payload. Notez que vous pouvez cliquer sur Coller une nouvelle payload si vous souhaitez modifier la payload actuellement transmise.
Payload envoyée : ce champ ne figure pas dans notre exemple. Il n’est disponible que si vous sélectionnez la méthode POST. Collez la payload qui sera envoyée au système tiers.
Dans le cas d’un appel GET nécessitant un ou plusieurs paramètres, vous devez indiquer ce(s) dernier(s) dans le champ Valeurs dynamiques. Ils sont alors automatiquement ajoutés à la fin de l’appel. Dans le cas d’un appel POST, vous devez :
répertorier les paramètres à transmettre au moment de l’appel dans le champ Valeurs dynamiques (« identifiant » dans l’exemple ci-dessous) ;
spécifier les paramètres avec la même syntaxe dans le corps de la payload envoyée. Pour ce faire, vous devez ajouter : « param » : « nom de votre paramètre » (« identifiant » dans l’exemple ci-dessous). Respectez la syntaxe ci-dessous :
{"id":{"param":"identifier"}}
Cliquez sur Enregistrer.
La source de données est maintenant configurée et prête à être utilisée dans vos parcours ; par exemple, dans vos conditions ou pour personnaliser un e-mail. Si la température est supérieure à 30° C, vous pouvez choisir d’envoyer une communication spécifique.
Ce mode d’authentification est utilisé pour une authentification complexe. Il est fréquemment utilisé pour appeler les protocoles d’encapsulage d’API, comme OAuth2, afin de récupérer un jeton d’accès à injecter dans la requête HTTP réelle pour l’action.
Lorsque vous configurez l’authentification personnalisée, vous pouvez cliquer sur le bouton ci-dessous pour vérifier si la payload d’authentification personnalisée est correctement configurée.
Si le test réussit, le bouton devient vert.
Avec cette authentification, l’exécution de l’action est un processus en deux étapes :
Cette authentification se compose de deux parties.
La définition du point d’entrée à appeler pour générer le jeton d’accès :
La définition de la méthode d’injection du jeton d’accès dans la requête HTTP de l’action :
authorizationType : définit la manière dont le jeton d’accès généré doit être injecté dans l’appel HTTP pour l’action. Les valeurs possibles sont les suivantes :
tokenInResponse : indique comment extraire le jeton d’accès de l’appel d’authentification. Cette propriété peut être :
Le format de cette authentification est le suivant :
{
"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>'"
}
Vous pouvez modifier la durée de mise en cache du jeton pour une source de données d’authentification personnalisée. Vous trouverez ci-dessous un exemple de payload d’authentification personnalisée. La durée de mise en cache est définie dans le paramètre « cacheDuration ». Elle spécifie la durée de conservation du jeton généré dans le cache. L’unité peut être en millisecondes, secondes, minutes, heures, jours, mois, années.
Voici un exemple pour le type d’authentification du porteur :
{
"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"
}
}
}
Le jeton d’authentification est mis en cache par parcours : si deux parcours utilisent la même action personnalisée, chaque parcours dispose de son propre jeton mis en cache. Ce jeton n’est pas partagé entre ces parcours.
La durée de mise en cache permet d’éviter un trop grand nombre d’appels aux points d’entrée d’authentification. La rétention des jetons d’authentification est mise en cache dans les services, il n’y a aucune persistance. Si un service est redémarré, il commence par un cache propre. Par défaut, la durée de mise en cache est de 1 heure. Dans la payload de l’authentification personnalisée, elle peut être adaptée en spécifiant une autre durée de rétention.
Voici un exemple pour le type d’authentification de l’en-tête :
{
"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"
}
Voici un exemple de réponse de l’appel API de connexion :
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S"
}