Sources de données externes concept_t2s_kqt_52b

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 :

  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. Saisissez un nom pour votre source de données.

    note note
    NOTE
    N'utilisez ni espaces ni caractères spéciaux. Utilisez 30 caractères au maximum.
  3. Ajoutez une description à votre source de données. Cette étape est facultative.

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

  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  : « clé API »
    • Valeur  : « 1234 » (valeur de la clé API)
    • Nom  : « appid » (il s’agit du nom du paramètre 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 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 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.
  • 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.
  • 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. Voir cette page.
  • 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" ("identifier" 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é section_wjp_nl5_nhb

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 :

  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 : 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",
    "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é. 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.

"authentication": {
    "type":"customAuthorization",
    "authorizationType":"Bearer",
    "endpoint":"http://localhost:${port}/epsilon/oauth2/access_token",
    "method":"POST",
    "headers": {
        "Authorization":"Basic EncodeBase64(${epsilonClientId}:${epsilonClientSecret})"
        },
    "body": {
        "bodyType":"form",
        "bodyParams": {
             "scope":"cn mail givenname uid employeeNumber",
             "grant_type":"password",
             "username":"${epsilonUserName}",
             "password":"${epsilonUserPassword}"
             }
        },
    "tokenInResponse":"json://access_token",
    "cacheDuration":
             { "duration":5, "timeUnit":"seconds" }
    }
NOTE
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.
recommendation-more-help
4f4a00c1-77c9-4eee-84df-bbe6206c3ab9