Sources de données externes external-data-sources
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 API REST utilisant POST ou GET et renvoyant JSON sont prises en charge. Les modes d’authentification par clé API, de base et personnalisée 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 d’appel API :
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
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 la clé API (appid).
Les principales étapes de création et de configuration d’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.
-
Saisissez un nom pour votre source de données.
note note NOTE Seuls les caractères alphanumériques et les traits de soulignement sont autorisés. La longueur maximale est de 30 caractères. -
Ajoutez une description à votre source de données. Cette étape est facultative.
-
Ajoutez l'URL du service externe. Dans notre exemple : https://api.adobeweather.org/weather.
note caution CAUTION 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 publiquement disponibles et des adresses IP n’est pas autorisée. 
-
Configurez l’authentification en fonction de la configuration du service externe : Aucune authentification, Simple, Personnalisée ou Clé API.
Pour le mode d’authentification simple, vous devez renseigner un nom d’utilisateur ou d’utilisatrice et un mot de passe.
note note NOTE Lorsque l’appel d’authentification est effectué, la chaîne <username>:<password>, codée en base64, est ajoutée dans l’en-tête Authentification.Pour plus d’informations sur le mode d’authentification personnalisée, reportez-vous à cette section. Dans notre exemple, nous choisissons le mode d’authentification de clé API :
- Type : « clé API »
- Nom : « appid » (il s’agit du nom du paramètre de la clé API)
- Valeur : « 1234 » (valeur de la clé API)
- Emplacement : « Paramètre de requête » (la clé API se trouve dans l’URL).
-
Ajoutez un nouveau groupe de champs pour chaque jeu de paramètres API en cliquant sur Ajouter un nouveau groupe de champs. Seuls les caractères alphanumériques et les traits de soulignement sont autorisés dans le nom du groupe de champs. La longueur maximale est de 30 caractères. Dans notre 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é dans : affiche le nombre de parcours qui utilisent un groupe de champs. Vous pouvez cliquer sur l’icône Afficher les parcours pour afficher la liste des parcours utilisant ce groupe de champs.
-
Méthode : sélectionnez la méthode POST ou GET. Dans notre cas, nous sélectionnons la méthode GET.
-
Valeurs dynamiques : saisissez les différents paramètres séparés par une virgule, « long,lat » dans notre exemple. Les valeurs des paramètres dépendant du contexte d’exécution, elles seront définies dans les parcours. En savoir plus
-
Payload de réponse : cliquez dans le champ Payload et collez un exemple du payload renvoyé par l’appel. Dans notre exemple, nous avons utilisé un payload trouvé sur un site web d’API météorologique. Vérifiez que les types de champ 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 un nouveau payload si vous souhaitez modifier le payload actuellement transmis.
-
Payload envoyé : ce champ n’apparaît pas dans notre exemple. Il n’est disponible que si vous sélectionnez la méthode POST. Collez le payload qui sera envoyé au système tiers.
Dans le cas d’une méthode GET nécessitant un ou plusieurs paramètres, vous saisissez le ou les paramètres dans le champ Valeurs dynamiques et ils sont automatiquement ajoutés à la fin de l’appel. Dans le cas d’un appel POST, vous devez procéder comme suit :
-
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). Suivez la syntaxe ci-dessous :
code language-none {"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.
Mode d’authentification personnalisé custom-authentication-mode
Ce mode d’authentification est utilisé pour une authentification complexe, fréquemment utilisée pour appeler les protocoles d’encapsulage d’API tels qu’OAuth2, afin de récupérer un jeton d’accès à injecter dans la requête HTTP réelle de l’action.
Lorsque vous configurez l’authentification personnalisée, vous pouvez cliquer sur le bouton ci-dessous pour vérifier si le payload de l’authentification personnalisée est correctement configuré.
Si le test est réussi, le bouton devient vert.
Avec cette authentification, l’exécution de l’action est un processus en deux étapes :
- Appelez le point d’entrée pour générer le jeton d’accès.
- Appelez l’API REST en injectant correctement le jeton d’accès.
Définition du point d’entrée à appeler pour générer le jeton d’accès custom-authentication-endpoint
-
endpoint : URL à utiliser pour générer le point d’entrée
-
Méthode de la requête HTTP sur le point d’entrée (GET ou POST)
-
headers : paires clé-valeur à injecter en tant qu’en-têtes dans cet appel, le cas échéant
-
body : décrit le corps de l’appel en cas d’utilisation de la méthode POST. Nous prenons en charge une structure de corps limitée, définie dans bodyParams (paires clé-valeur). bodyType décrit le format et le codage du corps dans l’appel :
- 'form' : signifie que le type de contenu sera application/x-www-form-urlencoded (jeu de caractères UTF-8) et que les paires clé/valeur seront sérialisées comme suit : key1=value1&key2=value2&…
- 'json' : signifie que le type de contenu sera application/json (jeu de caractères UTF-8) et que les paires clé-valeur seront sérialisées sous la forme d’un objet json, tel quel : { "key1": "value1", "key2": "value2", …}
Définition de la méthode d’injection du jeton d’accès dans la requête HTTP de l’action custom-authentication-access-token
-
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 :
- bearer : indique que le jeton d’accès doit être injecté dans l’en-tête Authorization, par exemple : Autorization: Bearer <access token>
- header : indique que le jeton d’accès doit être injecté en tant qu’en-tête, le nom de l’en-tête étant défini par la propriété tokenTarget. Par exemple, si tokenTarget est myHeader, le jeton d’accès est injecté sous la forme d’un en-tête : myHeader: <access token>
- queryParam : indique que le jeton d’accès doit être injecté en tant que queryParam, le nom du paramètre de requête étant défini par la propriété tokenTarget. Par exemple, si tokenTarget est myQueryParam, l’URL de l’appel d’action est : <url>?myQueryParam=<access token>
-
tokenInResponse : indique comment extraire le jeton d’accès de l’appel d’authentification. Cette propriété peut être l’un des éléments suivants :
- 'response' : indique que la réponse HTTP est le jeton d’accès ;
- un sélecteur dans un fichier JSON (en supposant que la réponse soit un fichier JSON, nous ne prenons pas en charge d’autres formats, tels que XML). Le format de ce sélecteur est json://<path to the access token property>. Par exemple, si la réponse de l’appel est : { "access_token": "theToken", "timestamp": 12323445656 }, tokenInResponse sera : json: //access_token.
Le format de cette authentification est le suivant :
{
"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'>",
}
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é. La durée de mise en cache est définie dans le paramètre « cacheDuration ». Il spécifie la durée de conservation du jeton généré dans le cache. L’unité peut être la milliseconde, la seconde, la minute, l’heure, le jour, le mois, ou l’année.
Voici un exemple pour le type d’authentification du porteur :
{
"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"
}
}
}
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",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
}
}
Voici un exemple de réponse de l’appel API de connexion :
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}