Prise en main de REST APIs

Informations sur les exigences générales, authentification, paramètres de requête facultatifs, requête URLs et autres références.

Configuration requise et recommandations pour l’API

Ce que vous devez faire et devez faire lorsque vous utilisez les Audience Manager APIs.

Notez ce qui suit lorsque vous utilisez le code API d’Audience Manager :

• Paramètres de requête : tous les paramètres de requête sont requis, sauf indication contraire.
• En-têtes de requête : lorsque vous utilisez des jetons d’ Adobe I/ , vous devez fournir l’ x-api-key en-tête . Vous pouvez obtenir votre clé API en suivant les instructions de la page Intégration de compte de service .
• JSONtype de contenu : indiquez content-type: application/json ** accept: application/json et dans votre code.
• Requêtes et réponses : envoyez des requêtes sous la forme d’un JSON objet correctement formaté. Audience Manager répond avec des données JSON formatées. Les réponses du serveur peuvent contenir les données demandées, un code d’état ou les deux.
• Accès : votre Audience Manager consultant vous fournira un identifiant client et une clé qui vous permettront d’effectuer API des requêtes.
• Documentation et exemples de code : le texte en ** italique représente une variable que vous fournissez ou transmettez lors de la création ou de la réception de API données. Remplacez italicized par votre propre code, paramètres ou d’autres informations requises.

Authentification

Audience Manager REST APIs prend en charge deux méthodes d’authentification.

• JWT (Service Account) Authentification à l’aide d’ Adobe I/O. Adobe I/O est l’écosystème de développement et la communauté de l’Adobe. Il comprend les outils de développement d’Adobe I/O et les API et API pour tous les produits d’Adobe. Il s’agit de la méthode recommandée pour configurer et utiliser Adobe APIs.
• Authentification OAuth (obsolète). Bien que cette méthode soit obsolète, les clients avec des intégrations OAuth existantes peuvent continuer à utiliser cette méthode.

JWT (Service Account) Authentification par Adobe I/O

Présentation des Adobes I/O

Adobe I/O est l’écosystème de développement et la communauté de l’Adobe. Il comprend les outils de développement d’Adobe I/O et les API et API pour tous les produits d’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, vérifiez que vous avez accès à Adobe Developer Console dans Adobe I/O. 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 I/O :

1. Connectez-vous à Adobe Developer Console.
2. Suivez les étapes de la section Connexion au compte de service.
   • Pendant É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.

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 Admin Console, sur la page Users.

   

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

OAuth Authentification (obsolète)

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

Créer un utilisateur générique API

Nous vous recommandons de créer un compte utilisateur technique distinct pour travailler avec les Audience Manager APIs. 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 API (par exemple, les appels provenant de vos applications qui utilisent nos APIs ou d’autres outils qui effectuent des demandes API).
• Accordez un accès ininterrompu aux APIs. 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 qui dispose des informations d’identification, de la clé et du secret appropriés pour effectuer des appels API. Cela s’avère également utile si vous développez vos propres applications qui utilisent les Audience Manager APIs.

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 workflow d’authentification par mot de passe d’un client JSON dans votre navigateur.

Étape 1 : Demande d’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 la balise 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

Actualisez les jetons pour renouveler 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 nouveau 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 la balise 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 se présenter comme suit :
  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.

Lancer des requêtes API authentifiées

Conditions requises pour appeler les méthodes API après réception d’un jeton d’authentification.

Pour lancer des appels par rapport aux méthodes API disponibles :

• Dans l’en-tête HTTP, définissez Authorization: Bearer <token>.
• Lors de l’utilisation de l’authentification JWT (compte de service), vous devez fournir l’en-tête x-api-key, qui sera identique à votre client_id. Vous pouvez obtenir votre client_id à partir de la page Intégration des Adobes I/O .
• Appelez la méthode API requise.

Paramètres de requête facultatifs API

Définissez les paramètres facultatifs disponibles pour les méthodes qui renvoient toutes les propriétés d’un objet.

Vous pouvez utiliser ces paramètres facultatifs avec des méthodes API qui renvoient les propriétés all d’un objet. Définissez ces options dans la chaîne de requête lors de la transmission de cette requête à API.

Remarque À Propos Des Options De Page

Lorsque les informations sur la page ne sont pas spécifiées, la requête renvoie la valeur "plain" JSON, ce qui génère un tableau. Si les informations sur la page sont spécifiées, la liste renvoyée est encapsulée dans un objet JSON contenant des informations sur le résultat total et la page active. Votre exemple de requête utilisant les options de page peut ressembler à ceci :

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs pour les demandes, les environnements d’évaluation et de production, ainsi que les versions.

Demande URLs

Le tableau suivant répertorie la requête URLs utilisée pour transmettre les requêtes API, par méthode.

Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre requête URLs en fonction des tableaux ci-dessous.

Demande URLs d’authentification JWT

Demande URLs d’authentification OAuth (obsolète)

Environnements

Les Audience Manager APIpermettent d’accéder à différents environnements de travail. Ces environnements vous aident à tester le code par rapport à des bases de données distinctes sans affecter les données de production en direct. Le tableau suivant répertorie les environnements API disponibles et les noms d’hôtes de ressources correspondants.

Selon la méthode d’authentification que vous utilisez, vous devez ajuster votre environnement URLs en fonction du tableau ci-dessous.

Versions

De nouvelles versions de ces APIs sont publiées régulièrement. Une nouvelle version incrémente le numéro de version API . Le numéro de version est référencé dans la requête URL sous la forme v<version number>, comme illustré dans l’exemple suivant :

https://<host>/v1/...

Codes de réponse définis

HTTP codes d’état et texte de réponse renvoyés par Audience Manager REST API.