Prise en main de REST APIs

Présentation d’Adobe Developer

Adobe Developer est l’écosystème et la communauté des développeurs de l’Adobe. Il comprend des API pour tous les produits Adobe.

Il s’agit de la méthode recommandée pour configurer et utiliser Adobe APIs.

Conditions préalables

Avant de pouvoir configurer l’authentification JWT, assurez-vous d’avoir accès au Adobe Developer Console dans Adobe Developer. Contactez l’administrateur de votre entreprise pour les demandes d’accès.

Authentification

Suivez les étapes ci-dessous pour configurer l’authentification JWT (Service Account) à l’aide de Adobe Developer :

1. Connectez-vous à Adobe Developer Console.
2. Suivez les étapes de la section Connexion au compte de service.
   • Pendant l’étape 2 : ajoutez une API à votre projet à l’aide de l’authentification du compte de service, sélectionnez l’option Audience Manager API .
3. Essayez la connexion en effectuant votre premier appel API en fonction des instructions de l’ étape 3.

NOTE

Pour configurer et utiliser automatiquement Audience Manager REST APIs, vous pouvez générer le JWT par programmation. Voir Authentification JWT (compte de service) pour obtenir des instructions détaillées.

Autorisations RBAC du compte technique

Si votre compte d’Audience Manager utilise le contrôle d’accès en fonction du rôle, vous devez créer un compte d’utilisateur technique d’Audience Manager et l’ajouter au groupe RBAC d’Audience Manager qui effectuera les appels d’API.

Pour créer un compte d’utilisateur technique et l’ajouter à un groupe RBAC, procédez comme suit :

1. Effectuez un appel GET à https://aam.adobe.io/v1/users/self. L’appel crée un compte utilisateur technique que vous pouvez voir dans la page Admin Console, dans la page Users.

   

2. Connectez-vous à votre compte d’Audience Manager et ajoutez le compte d’utilisateur techniqueau groupe d’utilisateurs qui effectuera les appels API.

WARNING

L’authentification et le renouvellement des jetons Audience Manager REST API via OAuth 2.0 sont désormais obsolètes.

Utilisez plutôt l’ authentification JWT (compte de service) .

Audience Manager REST API suit les OAuth 2.0 standards pour l’authentification et le renouvellement des jetons. Les sections ci-dessous décrivent comment vous authentifier et commencer à utiliser les API.

Création d’un utilisateur générique API

Nous vous recommandons de créer un compte utilisateur technique distinct pour travailler avec les Audience Manager API. Il s’agit d’un compte générique qui n’est pas lié ou associé à un utilisateur spécifique de votre entreprise. Ce type de compte utilisateur API vous permet d’accomplir 2 tâches :

• Identifiez le service qui appelle le API (par exemple, les appels de vos applications qui utilisent nos API ou d'autres outils qui effectuent des requêtes API).
• Accordez un accès ininterrompu aux API. Un compte lié à une personne spécifique peut être supprimé lorsqu’il quitte votre société. Cela vous empêchera de travailler avec le code API disponible. Un compte générique qui n’est pas lié à un employé spécifique vous permet d’éviter ce problème.

Par exemple, pour ce type de compte, supposons que vous souhaitiez modifier de nombreux segments à la fois avec les outils de gestion en bloc. Pour ce faire, votre compte utilisateur doit disposer d’un accès API. Au lieu d’ajouter des autorisations à un utilisateur spécifique, créez un compte utilisateur API non spécifique disposant des informations d’identification, de la clé et du secret appropriés pour effectuer des appels API. Ceci est également utile si vous développez vos propres applications qui utilisent les Audience Manager API.

Contactez votre consultant Audience Manager pour configurer un compte utilisateur générique API uniquement.

Processus d’authentification par mot de passe

L'authentification par mot de passe sécurise l'accès à notre REST API. Les étapes ci-dessous décrivent le processus d’authentification par mot de passe d’un client JSON dans votre navigateur.

TIP

Chiffrez l’accès et actualisez les jetons si vous les stockez dans une base de données.

Étape 1 : Demander l’accès à API

Contactez votre responsable Partenaires en solutions . Ils vous fourniront un ID client API et un secret. L’identifiant et le secret vous authentifient dans le API.

Remarque : Si vous souhaitez recevoir un jeton d’actualisation, indiquez-le lorsque vous demandez l’accès à API.

Étape 2 : demander le jeton

Transmettez une requête de jeton avec votre client JSON préféré. Lorsque vous créez la requête :

• Utilisez une méthode POST pour appeler https://api.demdex.com/oauth/token.
• Convertissez votre ID client et votre secret client en chaîne codée en base 64. Séparez l’ID et le secret par deux points au cours du processus de conversion. Par exemple, les informations d’identification testId : testSecret sont converties en dGVzdElkOnRlc3RTZWNyZXQ=.
• Transmettez HTTP headers Authorization:Basic <base-64 clientID:clientSecret> et Content-Type: application/x-www-form-urlencoded . Par exemple, votre en-tête peut ressembler à ceci :
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Configurez le corps de la requête comme suit :
  
  grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Étape 3 : Réception du jeton

La réponse JSON contient votre jeton d’accès. La réponse doit se présenter comme suit :

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

La clé expires_in représente le nombre de secondes jusqu’à l’expiration du jeton d’accès. Pour respecter les bonnes pratiques, utilisez de courts délais d’expiration pour limiter l’exposition si le jeton est un jour exposé.

Actualiser le jeton

Les jetons d’actualisation renouvellent l’accès à API après l’expiration du jeton d’origine. Si nécessaire, la réponse JSON du workflow de mot de passe inclut un jeton d’actualisation. Si vous ne recevez pas de jeton d’actualisation, créez-en un nouveau par le biais du processus d’authentification par mot de passe.

Vous pouvez également utiliser un jeton d’actualisation pour générer un nouveau jeton avant l’expiration du jeton d’accès existant.

Si votre jeton d’accès a expiré, vous recevez un 401 Status Code et l’en-tête suivant dans la réponse :

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

Les étapes suivantes décrivent le processus d’utilisation d’un jeton d’actualisation pour créer un jeton d’accès à partir d’un client JSON dans votre navigateur.

Étape 1 : demander le nouveau jeton

Transmettez une requête de jeton d’actualisation avec votre client JSON préféré. Lorsque vous créez la requête :

• Utilisez une méthode POST pour appeler https://api.demdex.com/oauth/token.
• Convertissez votre ID client et votre secret client en chaîne codée en base 64. Séparez l’ID et le secret par deux points au cours du processus de conversion. Par exemple, les informations d’identification testId : testSecret sont converties en dGVzdElkOnRlc3RTZWNyZXQ=.
• Transmettez les en-têtes HTTP Authorization:Basic <base-64 clientID:clientSecret> et Content-Type: application/x-www-form-urlencoded. Par exemple, votre en-tête peut ressembler à ceci :
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Dans le corps de la requête, spécifiez le grant_type:refresh_token et transmettez le jeton d’actualisation que vous avez reçu dans votre demande d’accès précédente. La requête doit ressembler à ceci :
  grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Étape 2 : réception du nouveau jeton

La réponse JSON contient votre nouveau jeton d’accès. La réponse doit se présenter comme suit :

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Code d’autorisation et authentification implicite

Audience Manager REST API prend en charge le code d’autorisation et l’authentification implicite. Pour utiliser ces méthodes d’accès, vos utilisateurs doivent se connecter à https://api.demdex.com/oauth/authorize pour accéder aux jetons et les actualiser.