Utilisation de Postman avec l’API Microsoft Graph

Article
03/15/2023
7 minutes de lecture

Postman est une plateforme d’API permettant de créer et d’utiliser des API. Postman simplifie chaque étape du cycle de vie des API et facilite la collaboration afin que vous puissiez créer de meilleures API plus rapidement.

Cet article explique comment utiliser l’API des connecteurs Microsoft Graph avec Postman.

Conditions préalables

Un compte Microsoft ou un compte professionnel ou scolaire.
Accéder à un client de développeur Microsoft 365. Si vous n’en avez pas, vous pouvez vous inscrire au Programme pour les développeurs Microsoft 365 pour obtenir un abonnement développeur gratuit.

Étape 1 : Dupliquer la collection Postman Microsoft Graph

Pour utiliser la collection Postman, vous devez la dupliquer dans votre espace de travail Postman. Cette opération s’effectue à partir d’un navigateur web.

Accédez à Postman et inscrivez-vous. Si vous avez déjà un compte Postman, vous pouvez procéder à la Connexion.
Une fois connecté, accédez à l’URL suivante : https://www.postman.com/microsoftgraph/workspace/microsoft-graph/collection/455214-085f7047-1bec-4570-9ed0-3a7253be148 et sélectionnez la collection Microsoft Graph.
Sélectionnez les trois points à droite, puis sélectionnez Créer une bifurcation.
Dans la boîte de dialogue qui s’ouvre, entrez une étiquette pour identifier votre bifurcation. Dans le menu déroulant Espace de travail , sélectionnez Mon espace de travail, puis sélectionnez Collection de bifurcation.
Accédez à Espaces de travail>Mon espace de travail pour voir la bifurcation que vous avez créée. Vous trouverez le dossier des connecteurs Microsoft Graph sous Application.

Étape 2 : Télécharger l’agent Postman (facultatif : navigateur web Postman uniquement)

Pour utiliser cette collection Postman dans votre navigateur web, téléchargez L’agent de bureau Postman.

Vous ne pouvez pas utiliser Postman pour le web sans cela en raison des restrictions CORS dans le navigateur web : « Nombre maximal de ressources de connexion par client Microsoft 365 ».

Vous n’avez pas besoin de l’agent si vous utilisez Postman pour l’application Windows. Si vous ouvrez Postman pour Windows, la collection s’affiche dans votre espace de travail.

Étape 3 : Créer une application Azure AD

Pour utiliser cette collection dans votre propre client de développeur, créez une application Azure Active Directory (Azure AD) et accordez-lui les autorisations appropriées pour les demandes que vous souhaitez appeler.

Accédez à portal.azure.com et connectez-vous avec votre compte administrateur client de développeur.
Sous Services Azure, sélectionnez Azure Active Directory.
Dans le menu gauche, sélectionnez Inscription des applications.
Dans le menu horizontal, sélectionnez Nouvel inscription.
Définissez le Nom de l’application à Parts Inventory.
Configurez L’URI de redirection à https://oauth.pstmn.io/v1/browser-callback.
Sélectionnez Inscrire.
Dans le menu gauche, sélectionnezAutorisations de l’API.
Dans le menu horizontal, sélectionnez Ajouter une autorisation>Autorisations déléguéesMicrosoft Graph> ou Autorisations d’application.
Commencez à taper External et choisissez les autorisations déléguées ou d’application nécessaires pour l’API que vous appelez. Pour plus d’informations, recherchez Autorisations de recherche dans les informations de référence sur les autorisations de graphe.
Sélectionnez Ajouter des autorisations.
Dans le menu horizontal, sélectionnez Accorder le consentement administrateur pour, puis sélectionnez Oui.
Dans le menu de gauche, sélectionnez Vue d’ensemble. À partir de là, vous pouvez obtenir l’ID d’application (client) et l’ID d’annuaire (client). Vous en aurez besoin à l’étape 4.
Dans le menu de gauche, sélectionnez Certificats et secrets .
Sélectionnez Clé secrète du nouveau client, entrez une description, puis sélectionnez Ajouter. Copiez la nouvelle clé secrète du client. Vous en aurez besoin à l’étape 4.

L’application dispose désormais de deux autorisations configurées. ExternalItem.ReadWrite.All est ajouté en tant qu’autorisation déléguée, qui est une autorisation qui nécessite un utilisateur connecté. L’application peut lire/écrire des éléments externes pour le compte de l’utilisateur. ExternalItem.ReadWrite.All est ajouté en tant qu’autorisation d’application, qui est une autorisation qui ne nécessite pas d’utilisateur connecté. L’application peut lire/écrire des éléments externes en son propre nom.

Étape 4 : Configuration de l'authentification

Dans cette étape, vous allez configurer les variables d’environnement dans Postman que vous utilisez pour récupérer un jeton d’accès.

Sélectionnez l’onglet Graph Microsoft et allez dans la section Variables.
Dans la section Variables, fournissez les informations requises à l’aide des informations de l’étape 3 :
- Définissez la valeur actuelle du Client sur la valeur d’ID d’annuaire (client) de l’étape 3.15.
- Définissez la valeur actuelle de client_id sur la valeur d’ID d’application (client) de l’étape 3.15.
- Définissez la valeur actuelle de client_secret sur la valeur de clé secrète client de l’étape 3.17.
- Définissez la valeur actuelle de userName sur admin@xxxxxxx.onmicrosoft.com.
- Définissez la Valeur actuelle de mot de passe sur le mot de passe d’administrateur client.
Sélectionnez Enregistrer / Mise à jour.

Step 5 : Obtenir un jeton d’authentification

Comme c’est la première fois que vous exécutez une demande en tant que flux d’authentification d’application, vous devez obtenir un jeton d’accès. Vous pouvez obtenir le jeton d’accès de l’application à l’aide de cette demande POST :

Capture d’écran de la section Obtenir le jeton d’accès de l’application

L’exemple suivant présente le comment obtenir un jeton d’accès avec un secret partagé :

POST /{{tenant}}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id={{client_id}} 
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default 
&client_secret={{client_secret}} 
&grant_type=client_credentials

Cet exemple présente une réponse réussie :

{ 
    "token_type": "Bearer", 
    "expires_in": 3599, 
    "ext_expires_in": 3599, 
    "access_token": "eyJ0eXAiOiJKV1QiLCJu… " 
}

Remarque

Vous utilisez le flux d’informations d’identification du client ici. Assurez-vous d’obtenir un jeton d’accès de l’application et non un jeton d’accès d’utilisateur.

Step 6 : Créer une connexion

Une connexion est un conteneur logique pour vos données externes que vous pouvez gérer comme une seule entité. Choisissez un nom de connexion, une description et un ID. Obtenez les informations nécessaires auprès de l’administrateur pour vous connecter à la source de données et fournissez un mécanisme d’autorisation par rapport à la source de contenu lors de la configuration de la connexion. Vous pouvez utiliser lekit de développement logiciel (SDK) Microsoft Graph et des APIs pour programmer la configuration de votre connecteur. Si vous voulez stocker des informations d’identification, vous pouvez utiliser Azure Key Vault.

POST /external/connections

Voici un exemple de demande.

POST https://graph.microsoft.com/beta/external/connections 
Content-type: application/json 

{ 
  "id": "contosotasks", 
  "name": "Contoso Tasks", 
  "description": "Connection to index Contoso task management system" 
}

Voici un exemple de réponse.

HTTP/1.1 201 Created 
Content-type: application/json 
 
{ 
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#connections/$entity", 
    "id": "contosotasks", 
    "name": "Contoso Tasks", 
    "description": "Connection to index Contoso task management system", 
    "state": null, 
    "configuration": { 
        "authorizedApps": [ 
            "a47b35b7-6271-4e6d-9e27-2450a8b9c6b6" 
        ] 
    } 
}

Voici une capture d’écran de la section Créer une connexion.

Capture d’écran de la section Créer une connexion.

Step 7 : Inscrire un schéma de connexion

Le schéma de connexion détermine la façon dont votre contenu est utilisé dans différentes expériences Microsoft Graph. Le schéma est une liste plate de toutes les propriétés que vous envisagez d’ajouter à la connexion, ainsi que les attributs, les étiquettes et les alias. Vous devez inscrire le schéma avant d’ajouter des éléments à la connexion.

POST /external/connections/{id}/schema

Voici un exemple de demande.

POST https://graph.microsoft.com/beta/external/connections/contosotasks/schema 
Content-type: application/json 
Prefer: respond-async 

{ 
  "baseType": "microsoft.graph.externalItem", 
  "properties": [ 
    { 
"name": "title", 
      "type": "String", 
      "isSearchable": "true", 
"isQueryable": "true", 
      "isRetrievable": "true", 
      "labels": [ 
        "title" 
      ] 
    }, 
    { 
"aliases": "creator", 
      "name": "createdBy", 
      "type": "String", 
      "isSearchable": "true", 
"isQueryable": "true", 
      "isRetrievable": "false", 
"isRefinable": "false", 
      "labels": [ 
        "createdBy" 
      ] 
    }, 
    { 
"aliases": "editedDate", 
      "name": "lastEditedDate", 
      "type": "DateTime", 
      "isSearchable": "false", 
"isQueryable": "true", 
      "isRetrievable": "true", 
"isRefinable": "true", 
      "labels": [ 
   "lastModifiedDateTime" 
] 
    } 
  ] 
}

Voici un exemple de réponse.

HTTP/1.1 202 Accepted 
Location: https://graph.microsoft.com/beta/external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Remarque

L’enregistrement du schéma de connexion est une opération asynchrone. Il ne faut donc pas insérer des éléments dans la connexion tant que le schéma de connexion n’est pas en état Terminé. Pour vérifier l’état du schéma de connexion, exécutez cette demande :

GET /external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Voici un autre exemple de la demande.

Request 
GET https://graph.microsoft.com/beta/external/connections/operations/616bfeed-666f-4ce0-8cd9-058939010bfc

Voici un autre exemple de réponse.

HTTP/1.1 200 OK 
Content-type: application/json 

{
    @odata.context":"https://graph.microsoft.com/beta/$metadata#external/connections('coursecatalog')/operations/$entity", 
    "id": "aa9186d2-893c-4361-ca51-431d88fa45d8", 
    "name": "Contoso Tasks", 
    "status": "inprogress", 
    "error": null  
}

Voici une capture d’écran de la section Obtenir l’état de l’opération de connexion.

Capture d’écran de la section Obtenir l’état d’une opération affichant l’état en cours

Une fois que l’état de l’opération de schéma de connexion est passé de En cours à Terminé, vous pouvez insérez des éléments pour la connexion.

Une fois que l’état de connexion est passé de brouillonàprêt, vous pouvez inger des éléments dans la connexion actuelle.

Étape 8 : Ajouter un membre de groupe externe (facultatif)

Si votre service externe utilise des listes de contrôle non-Azure AD, synchronisez ces autorisations.

Les groupes externes (ainsi que les utilisateurs et groupes Azure Active Directory) servent à définir des autorisations sur les externalItems ajoutées à une connexion Microsoft Graph. Pour plus d’informations, consultez externalGroup.

Voici un exemple de requête.

POST https://graph.microsoft.com/beta/external/connections/contosotasks/groups/31bea3d537902000/members 
Content-Type: application/json 
 
{ 
  "@odata.type": "#microsoft.graph.externalGroupMember", 
  "id": "1431b9c38ee647f6a", 
  "type": "group", 
  "identitySource": "external" 
}

Voici un exemple de réponse.

HTTP/1.1 201 Created 
Content-Type: application/json 

{ 
  "@odata.type": "#microsoft.graph.externalGroupMember", 
  "id": "14m1b9c38qe647f6a", 
  "type": "group", 
  "identitySource": "external" 
}

Étape 9 : Insérer des éléments

Après avoir créé une connexion, vous pouvez ajouter votre contenu. Chaque élément de votre source de données doit être représenté sous la forme d’un externalItem dans Microsoft Graph avec un ID d’élément unique. Cet ID sert à créer, mettre à jour, ou supprimer l’élément dans Microsoft Graph. Vous pouvez utiliser la clé primaire de votre source de données en tant que itemId ou la dériver d’un ou plusieurs champs. Une valeur externalItem possède trois composants clés : liste de contrôle d’accès, les propriétés, et le contenu.

Si vous avez des fichiers binaires, vous devez analyser pour obtenir les métadonnées et une version textuelle du contenu. Si vous avez du contenu non textuel tel qu’un fichier PDF ou BMP, vous devez utiliser la reconnaissance des caractères d’objet pour convertir le contenu en texte.

Vous êtes responsable de la conversion des autorisations sources à grant ou deny. Deny a une plus grande priorité par rapport à grant.

Voici un exemple de requête.

PUT https://graph.microsoft.com/beta/external/connections/contosohr/items/TSP228082938 
Content-type: application/json 

{ 
  "@odata.type": "microsoft.graph.externalItem", 
  "acl": [ 
    { 
      "type": "user", 
      "value": "e811976d-83df-4cbd-8b9b-5215b18aa874", 
      "accessType": "grant", 
      "identitySource": "azureActiveDirectory" 
    }, 
    { 
      "type": "group", 
      "value": "14m1b9c38qe647f6a", 
      "accessType": "deny", 
      "identitySource": "external" 
    } 
  ], 
  "properties": { 
    "ticketID": "1158", 
    "priority": 1, 
    "title": "Filter design", 
  }, 
  "content": { 
    "value": "Build filtering capability by...", 
    "type": "text" 
  } 
}

Voici un exemple de réponse réussie.

HTTP/1.1 200 OK

Gestion des erreurs

Pour plus d’informations sur la résolution des erreurs, consultez Résoudre les erreurs d’autorisation de Microsoft Graph.

Voir aussi

Utilisation de Postman avec l’API Microsoft Graph

Utilisation de Postman avec l’API Microsoft Graph

Conditions préalables

Étape 1 : Dupliquer la collection Postman Microsoft Graph

Étape 2 : Télécharger l’agent Postman (facultatif : navigateur web Postman uniquement)

Étape 3 : Créer une application Azure AD

Étape 4 : Configuration de l'authentification

Step 5 : Obtenir un jeton d’authentification

Step 6 : Créer une connexion

Step 7 : Inscrire un schéma de connexion

Étape 8 : Ajouter un membre de groupe externe (facultatif)

Étape 9 : Insérer des éléments

Gestion des erreurs

Voir aussi

Ressources supplémentaires

Ressources supplémentaires