Sources de données externes

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 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 :

• 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 de la clé API (appid).

Les principales étapes nécessaires pour créer et configurer une source de données externe sont les suivantes :

1. 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.

   

2. Attribuez un nom à votre source de données.

   REMARQUE

   N'utilisez ni espaces ni caractères spéciaux. Utilisez 30 caractères au maximum.

3. Ajoutez une description à la source de données. Cette étape est facultative.

4. Ajoutez l'URL du service externe. Dans notre exemple : https://api.adobeweather.org/weather.

   ATTENTION

   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.

   

5. 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 :

   • Type : « API key »
   • 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)

   

6. 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.

Mode d’authentification personnalisé

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 :

1. Appelez le point d’entrée pour générer le jeton d’accès.
2. Appelez l’API REST en injectant correctement le jeton d’accès.

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 :

• 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", …}

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 :

  • bearer : indique que le jeton d’accès doit être injecté dans l’en-tête Authorization ; par exemple, Authorization: Bearer <jeton d’accès>
  • header : indique que le jeton d’accès doit être injecté en tant qu’en-tête ; nom d’en-tête défini par la propriété tokenTarget. Par exemple, si la propriété tokenTarget est myHeader, le jeton d’accès est injecté sous la forme d’un en-tête : myHeader: <jeton d’accès>.
  • queryParam : indique que le jeton d’accès doit être injecté en tant que queryParam, le nom du paramètre de requête défini par la propriété tokenTarget. Par exemple, si le paramètre tokenTarget est myQueryParam, l’URL de l’appel d’action est <url>?myQueryParam=<jeton d’accès>

• tokenInResponse : indique comment extraire le jeton d’accès de l’appel d’authentification. Cette propriété peut être :

  • '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 au format JSON ; les autres formats, comme XML, ne sont pas pris en charge). Le format de ce sélecteur est json://<chemin d’accès à la propriété du jeton d’accès>. 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",
    "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"
    }
  }
}

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