Authentification et accès aux API Experience Platform

Ce document fournit un tutoriel détaillé pour accéder à un compte de développeur Adobe Experience Platform afin d’effectuer des appels API Experience Platform. À la fin de ce didacticiel, vous aurez généré les informations d’identification suivantes requises pour tous les appels d’API de plate-forme :

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {IMS_ORG}

Pour maintenir la sécurité de vos applications et de vos utilisateurs, toutes les requêtes aux API Adobe I/O doivent être authentifiées et autorisées à l’aide de normes telles que OAuth et JSON Web Tokens (JWT). Un JWT est utilisé avec des informations spécifiques au client pour générer votre jeton d'accès personnel.

Ce didacticiel explique comment rassembler les informations d’identification requises pour authentifier les appels d’API de plate-forme, comme indiqué dans l’organigramme suivant :

Conditions préalables

Pour pouvoir invoquer les API Experience Platform avec succès, vous devez disposer des éléments suivants :

  • Une organisation IMS ayant accès à Adobe Experience Platform.
  • Administrateur Admin Console capable de vous ajouter en tant que développeur et utilisateur pour un profil de produits.

Vous devez également disposer d’une Adobe ID pour compléter ce didacticiel. Si vous ne possédez pas d’Adobe ID, vous pouvez en créer un en suivant les étapes suivantes :

  1. Accédez à Adobe Developer Console.
  2. Sélectionnez Créer un nouveau compte.
  3. Terminez le processus d'inscription.

Obtenir l'accès des développeurs et des utilisateurs pour les Experience Platform

Avant de créer des intégrations sur Adobe Developer Console, votre compte doit disposer d’autorisations de développeur et d’utilisateur pour un profil de produits Experience Platform à Adobe Admin Console.

Obtenir un accès en tant que développeur

Contactez un administrateur Admin Console de votre organisation pour vous ajouter en tant que développeur à un profil de produit Experience Platform en utilisant Admin Console. Consultez la documentation Admin Console pour obtenir des instructions spécifiques sur la façon de gérer l'accès des développeurs pour les profils de produits.

Une fois que vous êtes affecté en tant que développeur, vous pouvez début à la création d'intégrations dans Adobe Developer Console. Ces intégrations constituent un pipeline allant des applications et services externes aux API d’Adobe.

Obtenir un accès en tant qu’utilisateur

Votre administrateur Admin Console doit également vous ajouter en tant qu'utilisateur au même profil de produits. Pour plus d’informations, consultez le guide intitulé gestion des groupes d’utilisateurs dans Admin Console.

Générer une clé d’API, un ID d’organisation IMS et un secret client

REMARQUE

Si vous suivez ce document du guide du développeur Privacy Service, vous pouvez maintenant revenir à ce guide pour générer les informations d’identification d’accès uniques à Privacy Service.

Une fois que vous avez obtenu l'accès des développeurs et des utilisateurs à la plate-forme via Admin Console, l'étape suivante consiste à générer vos {IMS_ORG} et {API_KEY} informations d'identification dans Adobe Developer Console. Ces informations d’identification ne doivent être générées qu’une seule fois et peuvent être réutilisées dans les prochains appels d’API de plate-forme.

Ajouter un Experience Platform à un projet

Accédez à Adobe Developer Console et connectez-vous avec votre Adobe ID. Suivez ensuite les étapes décrites dans le didacticiel sur la création d'un projet vide dans la documentation de la Console développeur de l'Adobe.

Après avoir créé un nouveau projet, sélectionnez Ajouter l'API dans l'écran Présentation du projet.

L'écran Ajouter une API s'affiche. Sélectionnez l’icône de produit pour Adobe Experience Platform, puis API Experience Platform avant de sélectionner Suivant.

À partir de là, suivez les étapes décrites dans le didacticiel sur l'ajout d'une API à un projet à l'aide d'un compte de service (JWT) (à partir de l'étape "Configurer l'API") pour terminer le processus.

IMPORTANT

A une certaine étape du processus lié ci-dessus, votre navigateur télécharge automatiquement une clé privée et un certificat public associé. Notez où cette clé privée est stockée sur votre ordinateur, car elle est requise à une étape ultérieure de ce didacticiel.

Collecte des informations d’identification

Une fois l'API ajoutée au projet, la page API Experience Platform du projet affiche les informations d'identification suivantes requises dans tous les appels aux API Experience Platform :

  • {API_KEY} (Identifiant du client)
  • {IMS_ORG} (ID d’organisation)

Outre les informations d’identification ci-dessus, vous aurez également besoin de la clé secrète client générée pour une étape ultérieure. Sélectionnez Récupérer le secret client pour révéler la valeur, puis copiez-la pour une utilisation ultérieure.

Générer un jeton Web JSON (JWT)

L’étape suivante consiste à générer un JSON Web Token (JWT) basé sur les informations d’identification de votre compte. Cette valeur est utilisée pour générer vos informations d’identification {ACCESS_TOKEN} à utiliser dans les appels d’API de plate-forme, qui doivent être régénérés toutes les 24 heures.

Sélectionnez Compte de service (JWT) dans le volet de navigation de gauche, puis Générer JWT.

Dans la zone de texte fournie sous Générer un JWT personnalisé, collez le contenu de la clé privée que vous avez générée précédemment lors de l’ajout de l’API de plateforme à votre compte de service. Sélectionnez ensuite Générer un jeton.

La page se met à jour pour afficher le fichier JWT généré, ainsi qu’un exemple de commande cURL qui vous permet de générer un jeton d'accès. Pour les besoins de ce didacticiel, sélectionnez Copier en regard de JWT généré pour copier le jeton dans le Presse-papiers.

Générer un jeton d'accès

Une fois que vous avez généré un JWT, vous pouvez l'utiliser dans un appel d'API pour générer votre {ACCESS_TOKEN}. Contrairement aux valeurs de {API_KEY} et {IMS_ORG}, un nouveau jeton doit être généré toutes les 24 heures pour continuer à utiliser les API de plateforme.

Requête

La requête suivante génère un nouveau {ACCESS_TOKEN} en fonction des informations d’identification fournies dans la charge utile. Ce point de terminaison accepte uniquement les données de formulaire en tant que charge utile. Par conséquent, il doit recevoir un en-tête Content-Type de multipart/form-data.

curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'
Propriété Description
{API_KEY} {API_KEY} (ID client) que vous avez récupéré au cours d’une étape précédente.
{SECRET} Secret client que vous avez récupéré à l'étape précédente.
{JWT} JWT que vous avez généré dans une étape précédente.
REMARQUE

Vous pouvez utiliser la même clé d’API, le même secret client et JWT pour générer un nouveau jeton d'accès pour chaque session. Vous pouvez ainsi automatiser la génération de jetons d'accès dans vos applications.

Réponse

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
Propriété Description
token_type Type de jeton renvoyé. Pour les jetons d'accès, cette valeur est toujours bearer.
access_token Le {ACCESS_TOKEN} généré. Cette valeur, précédée du mot Bearer, est requise en tant qu'en-tête Authentication pour tous les appels d'API de plate-forme.
expires_in Nombre de millisecondes restantes jusqu’à l’expiration du jeton d'accès. Une fois cette valeur atteinte, un nouveau jeton d'accès doit être généré pour continuer à utiliser les API de plateforme.

Tester les informations d’accès

Une fois que vous avez rassemblé les trois informations d’identification requises, vous pouvez effectuer l’appel d’API suivant. Cet appel liste toutes les classes Experience Data Model (XDM) standard disponibles pour votre entreprise.

Requête

curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

Réponse

Si votre réponse est similaire à celle illustrée ci-dessous, vos informations d’identification sont valides et fonctionnent. (Cette réponse a été tronquée pour l’espace.)

{
  "results": [
    {
        "title": "XDM ExperienceEvent",
        "$id": "https://ns.adobe.com/xdm/context/experienceevent",
        "meta:altId": "_xdm.context.experienceevent",
        "version": "1"
    },
    {
        "title": "XDM Individual Profile",
        "$id": "https://ns.adobe.com/xdm/context/profile",
        "meta:altId": "_xdm.context.profile",
        "version": "1"
    }
  ]
}

Utilisez Postman pour authentifier et tester les appels d'API

🔗 Postmanis est un outil populaire qui permet aux développeurs d'explorer et de tester les API RESTful. Cette publication moyenne décrit comment vous pouvez configurer Postman pour qu'il exécute automatiquement l'authentification JWT et l'utilise pour consommer les API de plateforme.

Étapes suivantes

En lisant ce document, vous avez rassemblé et testé avec succès vos informations d’identification d’accès pour les API de plateformes. Vous pouvez désormais suivre l'exemple d'appels d'API fourni dans la documentation.

Outre les valeurs d'authentification que vous avez rassemblées dans ce didacticiel, de nombreuses API de plateformes nécessitent également un {SANDBOX_NAME} valide pour être fourni en-tête. Pour plus d’informations, consultez la présentation des environnements de test.

Sur cette page