S’authentifier et accéder aux API Experience Platform
Ce document fournit un tutoriel détaillé permettant d’accéder à un compte de développeur Adobe Experience Platform afin d’effectuer des appels vers des API Experience Platform. À la fin de ce tutoriel, vous aurez généré ou collecté les informations d’identification suivantes, requises en tant qu’en-têtes dans tous les appels d’API Platform :
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
{SANDBOX_NAME}
valide soit fourni en tant qu’en-tête. Pour plus d’informations sur les environnements de test et la documentation sandbox management endpoint pour plus d’informations sur la liste des environnements de test disponibles pour votre organisation, consultez la présentation des environnements de test .Pour maintenir la sécurité de vos applications et de vos utilisateurs, toutes les demandes aux API Experience Platform doivent être authentifiées et autorisées à l’aide de normes telles que OAuth.
Ce tutoriel explique comment rassembler les informations d’identification requises pour authentifier les appels API Platform, comme décrit dans l’organigramme ci-dessous. Vous pouvez rassembler la plupart des informations d’identification requises dans la configuration initiale unique. Le jeton d’accès doit toutefois être actualisé toutes les 24 heures.
Conditions préalables prerequisites
Pour passer avec succès des appels à des API Experience Platform, vous devez disposer des éléments suivants :
- Une organisation ayant accès à Adobe Experience Platform.
- Administrateur Admin Console capable de vous ajouter en tant que développeur et utilisateur pour un profil de produit.
- Administrateur système Experience Platform qui peut vous accorder les contrôles d’accès basés sur les attributs nécessaires pour effectuer des opérations de lecture ou d’écriture sur différentes parties de l’Experience Platform via les API.
Vous devez également disposer d’un Adobe ID pour suivre ce tutoriel. Si vous ne possédez pas d’Adobe ID, vous pouvez en créer un en suivant les étapes suivantes :
- Accédez à Adobe Developer Console.
- Sélectionnez Créer un compte.
- Terminez le processus d’inscription.
Obtenir un accès développeur et utilisateur pour les Experience Platform gain-developer-user-access
Avant de créer des intégrations sur Adobe Developer Console, votre compte doit disposer des autorisations de développeur et d’utilisateur pour un profil de produit Experience Platform dans Adobe Admin Console.
Obtenir un accès en tant que développeur gain-developer-access
Contactez un administrateur Admin Console de votre entreprise pour vous ajouter en tant que développeur à un profil de produit Experience Platform à l’aide de Admin Console. Consultez la documentation Admin Console pour obtenir des instructions spécifiques sur la gestion de l’accès des développeurs pour les profils de produits.
Une fois que vous avez été affecté en tant que développeur, vous pouvez commencer à créer des intégrations dans Adobe Developer Console. Ces intégrations constituent un pipeline allant des applications et services externes vers les API d’Adobe.
Obtenir un accès utilisateur gain-user-access
Votre administrateur Admin Console doit également vous ajouter en tant qu’utilisateur au même profil de produit. Avec l’accès utilisateur, vous pouvez voir dans l’interface utilisateur le résultat des opérations de l’API que vous effectuez.
Pour plus d’informations, consultez le guide sur la gestion des groupes d’utilisateurs dans Admin Console .
Génération d’une clé API (ID client) et d’un ID d’organisation generate-credentials
Une fois que vous avez reçu un accès utilisateur et développeur à Platform via Admin Console, l’étape suivante consiste à générer vos informations d’identification {ORG_ID}
et {API_KEY}
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 futurs appels d’API Platform.
Ajouter un Experience Platform à un projet add-platform-to-project
Accédez à Adobe Developer Console et connectez-vous avec votre Adobe ID. Suivez ensuite les étapes décrites dans le tutoriel sur la création dʼun projet vide disponible dans la documentation dʼAdobe Developer Console.
Une fois que vous avez créé un projet, sélectionnez Ajouter une API sur l’écran Project Overview (Aperçu 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.
Sélectionnez le type d'authentification OAuth Server-to-Server select-oauth-server-to-server
Sélectionnez ensuite le type d'authentification OAuth Server-to-Server pour générer des jetons d'accès et accéder à l'API Experience Platform.
Sélection des profils de produit pour votre intégration select-product-profiles
Dans l’écran Configurer l’API, sélectionnez AEP-Default-All-Users.
Sélectionnez Enregistrer l’API configurée lorsque vous êtes prêt.
Une présentation des étapes décrites ci-dessus pour configurer une intégration avec l’API Experience Platform est également disponible dans le tutoriel vidéo ci-dessous :
Collecte des informations d’identification gather-credentials
Une fois que l’API a été 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}
(ID client){ORG_ID}
(ID d’organisation)
Générer un jeton d’accès generate-access-token
L’étape suivante consiste à générer des informations d’identification {ACCESS_TOKEN}
à utiliser dans les appels d’API Platform. Contrairement aux valeurs de {API_KEY}
et {ORG_ID}
, un nouveau jeton doit être généré toutes les 24 heures pour continuer à utiliser les API Platform. Sélectionnez Générer un jeton d’accès, comme illustré ci-dessous.
[Obsolète]{class="badge informative"} Générer un jeton Web JSON (JWT) jwt
L’étape suivante consiste à générer un jeton Web JSON (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 API Platform, qui doivent être régénérés toutes les 24 heures.
note important |
---|
IMPORTANT |
Pour les besoins de ce tutoriel, les étapes ci-dessous indiquent comment générer un jeton JWT dans Developer Console. Cependant, cette méthode de génération ne doit être utilisée qu’à des fins de test et d’évaluation. |
Pour une utilisation régulière, le jeton JWT doit être généré automatiquement. Pour plus d’informations sur la génération par programmation de JWT, consultez le guide d’authentification du compte de service sur Adobe Developer. |
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 Generate custom JWT, collez le contenu de la clé privée que vous avez précédemment générée lors de l’ajout de l’API Platform à votre compte de service. Sélectionnez ensuite Générer un jeton.
La page se met à jour pour afficher le 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 tutoriel, sélectionnez Copier en regard de JWT généré pour copier le jeton dans votre 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 API pour générer votre {ACCESS_TOKEN}
. Contrairement aux valeurs de {API_KEY}
et {ORG_ID}
, un nouveau jeton doit être généré toutes les 24 heures pour continuer à utiliser les API Platform.
Requête
La requête suivante génère un nouveau {ACCESS_TOKEN}
en fonction des informations d’identification fournies dans la payload. Ce point de terminaison accepte uniquement les données de formulaire comme charge utile. Il doit donc recevoir un en-tête Content-Type
de multipart/form-data
.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propriété | Description |
{API_KEY} |
{API_KEY} (ID client) que vous avez récupéré dans une étape précédente. |
{SECRET} |
Le secret client que vous avez récupéré dans une étape précédente. |
{JWT} |
JWT que vous avez généré dans une étape précédente. |
note note |
---|
NOTE |
Vous pouvez utiliser la même clé 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 des jetons d’accès dans vos applications. |
Réponse
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propriété | Description |
token_type |
Le type of jeton en cours de renvoi. Pour les jetons d’accès, cette valeur est toujours bearer . |
access_token |
{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 Platform. |
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 Platform. |
Tester les informations d’accès test-credentials
Une fois que vous avez rassemblé les trois informations d’identification requises - jeton d’accès, clé d’API et ID d’organisation - , vous pouvez effectuer l’appel API suivant. Cet appel répertorie toutes les classes Experience Data Model (XDM) standard disponibles pour votre organisation. Importez et exécutez l’appel dans Postman.
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: {{ORG_ID}}'
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"
}
]
}
Obtention des autorisations de contrôle d’accès basées sur les attributs nécessaires get-abac-permissions
Pour accéder à plusieurs ressources ou les modifier dans Experience Platform, vous devez disposer des autorisations de contrôle d’accès appropriées. Les administrateurs système peuvent vous accorder les autorisations dont vous avez besoin. Pour plus d’informations, reportez-vous à la section sur la gestion des informations d’identification de l’API pour un rôle.
Des informations détaillées sur la manière dont un administrateur système peut accorder les autorisations requises pour accéder aux ressources Platform via l’API sont également disponibles dans le tutoriel vidéo ci-dessous :
Utilisation de Postman pour authentifier et tester les appels API use-postman
Postman est un outil populaire qui permet aux développeurs d’explorer et de tester les API RESTful. Vous pouvez utiliser les collections et environnements Postman Experience Platform pour accélérer votre travail avec les API Experience Platform. En savoir plus sur l’utilisation de Postman dans Experience Platform et la prise en main des collections et des environnements.
Des informations détaillées sur l’utilisation de Postman avec des collections et des environnements Experience Platform sont également disponibles dans les tutoriels vidéo ci-dessous :
Télécharger et importer un environnement Postman à utiliser avec les API Experience Platform
Utiliser une collection Postman pour générer des jetons d’accès
Téléchargez la collection Postman Identity Management Service et regardez la vidéo ci-dessous pour découvrir comment générer des jetons d’accès.
Télécharger des collections Postman d’API Experience Platform et interagir avec les API
Administrateurs système : octroi aux développeurs et aux API d’un contrôle d’accès avec des autorisations d’Experience Platform grant-developer-and-api-access-control
Avant de créer des intégrations sur Adobe Developer Console, votre compte doit disposer des autorisations de développeur et d’utilisateur pour un profil de produit Experience Platform dans Adobe Admin Console.
Ajout de développeurs à un profil de produit add-developers-to-product-profile
Accédez à Admin Console et connectez-vous avec votre Adobe ID.
Sélectionnez Produits, puis Adobe Experience Platform dans la liste des produits.
Dans l’onglet Profils de produit, sélectionnez AEP-Default-All-Users. Vous pouvez également utiliser la barre de recherche pour rechercher le profil de produit en saisissant son nom.
Sélectionnez l’onglet Développeurs, puis sélectionnez Ajouter développeur.
Saisissez le Email ou nom d’utilisateur du développeur. Un email ou nom d’utilisateur valide affiche les détails du développeur. Sélectionnez Enregistrer.
Le développeur a été ajouté avec succès et apparaît sur l’onglet Développeurs .
Attribution d’une API à un rôle
Un administrateur système peut affecter des API aux rôles dans l’interface utilisateur de l’Experience Platform.
Sélectionnez Permissions et le rôle auquel vous souhaitez ajouter l’API. Sélectionnez l’onglet Informations d’identification de l’API, puis sélectionnez Ajouter les informations d’identification de l’API.
Sélectionnez l’API que vous souhaitez ajouter au rôle, puis sélectionnez Enregistrer.
Vous revenez à l’onglet Informations d’identification de l’API, où l’API nouvellement ajoutée est répertoriée.
Ressources supplémentaires additional-resources
Reportez-vous aux ressources supplémentaires liées ci-dessous pour plus d’informations sur la prise en main des API Experience Platform.
- Page de tutoriels vidéo Authentification et accès aux API Experience Platform
- Identity Management Service Postman Collection pour générer des jetons d’accès
- Collections Postman de l’API Experience Platform
Étapes suivantes next-steps
En lisant ce document, vous avez rassemblé et testé avec succès vos informations d’identification d’accès pour les API Platform. Vous pouvez désormais suivre les exemples d’appels API fournis dans la documentation.
Outre les valeurs d’authentification que vous avez collectées dans ce tutoriel, de nombreuses API Platform nécessitent également qu’un {SANDBOX_NAME}
valide soit fourni en tant qu’en-tête. Pour plus d’informations, consultez la Présentation des sandbox.