Utilisation de Postman avec l’API Microsoft Graph

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édez à 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 gratuit de développeur.

Étape 1 : Dupliquer la collection Postman Microsoft Graph

Pour utiliser la collection Postman, vous devez l'intégrer dans votre espace de travail Postman. Faites-le à partir d'un navigateur Web.

  1. Accédez à Postman et inscrivez-vous. Si vous avez déjà un compte Postman, vous pouvez procéder à la Connexion.

  2. 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.

  3. Sélectionnez les trois points à droite, puis sélectionnez Créer une bifurcation.

    Capture d’écran montrant la collection Graph Microsoft dans Postman et l’option de création d’une bifurcation

  4. 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.

    Capture d'écran montrant le dialogue de collecte de fourchettes dans Postman et les options permettant d'entrer une étiquette et de sélectionner Mon espace de travail.

  5. 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.

    Capture d’écran de la section Mon espace de travail dans Postman, montrant la collection Graph Microsoft

É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.

  1. Accédez à portal.azure.com et connectez-vous avec votre compte administrateur client de développeur.
  2. Sous Services Azure, sélectionnez Azure Active Directory.
  3. Dans le menu gauche, sélectionnez Inscription des applications.
  4. Dans le menu horizontal, sélectionnez Nouvel inscription.
  5. Définissez le Nom de l’application à Parts Inventory.
  6. Configurez L’URI de redirection à https://oauth.pstmn.io/v1/browser-callback.
  7. Sélectionnez Inscrire.
  8. Dans le menu gauche, sélectionnez Autorisations de l’API.
  9. Dans le menu horizontal, sélectionnez Ajouter une autorisation > Microsoft Graph > Autorisations déléguées.
  10. Commencez à taper ExternalItem.ReadWrite.All et sélectionnez ExternalItem.ReadWrite.All.
  11. Sélectionnez Autorisations d’application, tapez ExternalItem, puis sélectionnez Autorisations d’application.
  12. Développez les options ExternalItem, puis sélectionnez ExternalItem.ReadWrite.All.
  13. Sélectionnez Ajouter des autorisations.
  14. Dans le menu horizontal, sélectionnez Accorder le consentement administrateur pour, puis sélectionnez Oui.
  15. 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.
  16. Dans le menu de gauche, sélectionnez Certificats et secrets.
  17. 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.

  1. Sélectionnez l’onglet Graph Microsoft et allez dans la section Variables.

    Capture d’écran de l’onglet d’API des connecteurs Microsoft Graph et la section Variables

  2. 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 d’ID_de client à la valeur de l’ID d’application (client) de l’étape 3.15.
    • Définissez la valeur actuelle de clé secrète_du client à la valeur de clé secrète du 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.

    Capture d’écran affichant les variables sélectionnées

  3. 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… " 
} 

Notes

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 

Notes

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) sont utilisés pour définir des autorisations sur externalItems ajoutés à 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