Créer un connecteur personnalisé Microsoft Graph JSON Batch pour Power Automate
Il existe plus de 230 connecteurs prêtes à l’emploi pour Microsoft Power Automate. La plupart de ces connecteurs utilisent Microsoft Graph pour communiquer avec des points de terminaison spécifiques de produits Microsoft. En outre, il existe d’autres scénarios où nous pouvons être amenés à appeler Microsoft Graph directement à partir de Power Automate à l’aide des blocs de construction de base du service, car il n’existe aucun connecteur qui communique directement avec Microsoft Graph pour couvrir l’ensemble de l’API.
Outre les scénarios d’appel direct de Microsoft Graph, un certain nombre de points de terminaison Microsoft API Graph prennent uniquement en charge les autorisations déléguées. Le connecteur HTTP dans Microsoft Power Automate permet des intégrations très flexibles, notamment l’appel de Microsoft Graph. Toutefois, le connecteur HTTP ne peut pas mettre en cache les informations d’identification d’un utilisateur pour activer des scénarios d’autorisation déléguée spécifiques. Dans ce cas, un connecteur personnalisé peut être créé pour fournir un wrapper autour de l’API Graph Microsoft et permettre l’utilisation de l’API avec des autorisations déléguées.
Ce labo couvre les deux scénarios ci-dessus. Tout d’abord, vous allez créer un connecteur personnalisé pour activer les intégrations avec Microsoft Graph qui nécessitent des autorisations déléguées. Ensuite, vous allez utiliser le point de terminaison de demande $batch pour fournir l’accès à toute la puissance de Microsoft Graph tout en utilisant les autorisations déléguées qui nécessitent la présence d’un utilisateur « connecté » dans une application.
Remarque
Il s’agit d’un tutoriel sur la création d’un connecteur personnalisé à utiliser dans Microsoft Power Automate et Azure Logic Apps. Ce tutoriel suppose que vous avez lu la vue d’ensemble du connecteur personnalisé pour comprendre le processus.
Prerequisites
Pour effectuer cet exercice dans ce billet, vous aurez besoin des éléments suivants :
- Accès administrateur à une location Microsoft 365. Si vous n’avez pas de locataire Microsoft 365, vous pouvez être éligible pour un client via le Programme pour les développeurs Microsoft 365 ; Pour plus d’informations, consultez la FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.
- Accès à Microsoft Power Automate.
Commentaires
Veuillez fournir des commentaires sur ce didacticiel dans le référentiel GitHub.
Créer une inscription d’application Azure AD
Dans cet exercice, vous allez créer une application Azure Active Directory qui sera utilisée pour fournir les autorisations déléguées pour le connecteur personnalisé.
Ouvrez un navigateur et accédez au Centre d’administration Azure Active Directory. Choisissez le lien Azure Active Directory dans le menu de navigation de gauche, puis choisissez l’entrée inscriptions d'applications dans la section Gérer du panneau Azure Active Directory.
Choisissez l’élément de menu Nouvelle inscription en haut du panneau Inscriptions d’applications .
Entrez MS Graph Batch App dans le champ Nom . Dans la section Types de comptes pris en charge , sélectionnez Comptes dans n’importe quel annuaire organisationnel. Laissez la section URI de redirection vide et choisissez Inscrire.
Dans le panneau Ms Graph Batch App, copiez l’ID d’application (client). Vous en aurez besoin dans l’exercice suivant.
Choisissez l’entrée Autorisations de l’API dans la section Gérer du panneau Ms Graph Batch App . Choisissez Ajouter une autorisation sous Autorisations d’API.
Dans le panneau Demander des autorisations d’API , choisissez Microsoft Graph, puis autorisations déléguées. Recherchez group, puis sélectionnez l’autorisation déléguée Lire et écrire tous les groupes . Choisissez Ajouter des autorisations en bas du panneau.
Choisissez l’entrée Certificats et secrets dans la section Gérer du panneau Ms Graph Batch App , puis choisissez Nouvelle clé secrète client. Entrez une description, choisissez une durée, puis sélectionnez Ajouter.
Copiez la valeur du nouveau secret. Vous en aurez besoin dans l’exercice suivant.
Importante
Cette étape est essentielle, car le secret ne sera pas accessible une fois que vous fermez ce panneau. Enregistrez ce secret dans un éditeur de texte pour l’utiliser dans les exercices à venir.
Pour activer la gestion des services supplémentaires accessibles via Microsoft Graph, y compris les propriétés Teams, vous devez sélectionner des étendues supplémentaires appropriées pour permettre la gestion de services spécifiques. Par exemple, pour étendre notre solution afin d’activer la création de blocs-notes OneNote ou de Planificateur plans, compartiments et tâches, vous devez ajouter les étendues d’autorisation requises pour les API appropriées.
Créer un lien personnalisé
Dans cet exercice, vous allez créer un connecteur personnalisé qui peut être utilisé dans Microsoft Power Automate ou dans Azure Logic Apps. Le fichier de définition OpenAPI est prédéfini avec le chemin d’accès correct pour le point de terminaison Microsoft Graph $batch et des paramètres supplémentaires pour permettre une importation simple.
Ouvrez un navigateur et accédez à Microsoft Power Automate. Connectez-vous avec votre compte d’administrateur de locataire Microsoft 365. Choisissez Données dans le menu de gauche, puis sélectionnez l’élément Connecteurs personnalisés dans le menu déroulant.
Il existe deux options pour créer un connecteur personnalisé pour Microsoft Graph :
- Créer à partir d’un espace vide
- Importer un fichier OpenAPI
Dans la page Connecteurs personnalisés , choisissez le lien Nouveau connecteur personnalisé en haut à droite, puis sélectionnez l’élément Créer à partir d’un élément vide dans le menu déroulant.
Entrez MS Graph Batch Connector dans la zone de texte Nom du connecteur . Choose Continue.
Dans la page Configuration du connecteur Général , renseignez les champs comme suit.
- Schéma : HTTPS
- Hôte :
graph.microsoft.com - URL de base :
/
Cliquez sur le bouton Sécurité pour continuer.
Dans la page Sécurité , renseignez les champs comme suit.
- Choisissez l’authentification implémentée par votre API :
OAuth 2.0 - Fournisseur d’identité :
Azure Active Directory - ID client : ID d’application que vous avez créé dans l’exercice précédent
- Clé secrète client : clé que vous avez créée dans l’exercice précédent
- URL de connexion :
https://login.windows.net - ID de locataire :
common - URL de la ressource :
https://graph.microsoft.com(pas de fin /) - Étendue : laissez vide
Cliquez sur le bouton Définition pour continuer.
Dans la page Définition , sélectionnez Nouvelle action et renseignez les champs comme suit.
- Résumé :
Batch - Description :
Execute Batch with Delegate Permission - ID de l’opération :
Batch - Visibilité :
important
Créez une demande en sélectionnant Importer à partir de l’exemple et renseignez les champs comme suit.
- Verbe :
POST - URL :
https://graph.microsoft.com/v1.0/$batch - En-têtes : laissez vide
- Corps :
{}
Sélectionnez Importer.
Choisissez Créer un connecteur en haut à droite.
Une fois le connecteur créé, copiez l’URL de redirection générée.
Retour à l’application inscrite dans le portail Azure que vous avez créé dans l’exercice précédent. Sélectionnez Authentification dans le menu de gauche. Sélectionnez Ajouter une plateforme, puis Web. Entrez l’URL de redirection copiée à l’étape précédente dans les URI de redirection, puis sélectionnez Configurer.
Autoriser le connecteur
La dernière étape de configuration pour s’assurer que le connecteur est prêt à être utilisé consiste à autoriser et tester le connecteur personnalisé pour créer une connexion mise en cache.
Importante
Les étapes suivantes nécessitent que vous soyez connecté avec des privilèges d’administrateur.
Dans Microsoft Power Automate, accédez à l’élément de menu Données à gauche et choisissez la page Connections. Cliquez sur le lien Nouvelle connexion .
Recherchez votre connecteur personnalisé et terminez la connexion en le sélectionnant, puis en choisissant Créer. Connectez-vous avec le compte Azure Active Directory de votre administrateur de locataire Microsoft 365.
Lorsque vous êtes invité à fournir les autorisations demandées, case activée Consentement au nom de votre organization, puis choisissez Accepter pour autoriser les autorisations.
Une fois que vous avez autorisé les autorisations, une connexion est créée dans Power Automate.
Le connecteur personnalisé est maintenant configuré et activé. Il peut y avoir un retard dans l’application et la disponibilité des autorisations, mais le connecteur est maintenant configuré.
Tester le traitement par lots dans l’afficheur Graph
Avant de créer un flux pour utiliser le nouveau connecteur, utilisez Microsoft Graph Explorer pour découvrir certaines des fonctionnalités et fonctionnalités du traitement par lots JSON dans Microsoft Graph.
Ouvrez le Explorer Microsoft Graph dans votre navigateur. Connectez-vous avec votre compte d’administrateur de locataire Microsoft 365. Recherchez Batch à partir des exemples de requêtes.
Sélectionnez l’exemple de requête Effectuer des GET parallèles dans le menu de gauche. Choisissez le bouton Exécuter la requête en haut à droite de l’écran.
L’exemple d’opération de traitement par lot traite trois requêtes HTTP GET et émet une seule requête HTTP POST au point de /v1.0/$batch terminaison Graph.
{
"requests": [
{
"url": "/me?$select=displayName,jobTitle,userPrincipalName",
"method": "GET",
"id": "1"
},
{
"url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview",
"method": "GET",
"id": "2"
},
{
"url": "/me/events",
"method": "GET",
"id": "3"
}
]
}
La réponse retournée est illustrée ci-dessous. Notez le tableau de réponses retourné par Microsoft Graph. Les réponses aux demandes traitées par lots peuvent apparaître dans un ordre différent de celui des requêtes dans le post. La id propriété doit être utilisée pour mettre en corrélation des demandes de lot individuelles avec des réponses de lot spécifiques.
Remarque
La réponse a été tronquée pour plus de lisibilité.
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
Chaque réponse contient une idpropriété , status, headerset body . Si la status propriété d’une requête indique un échec, contient toutes les body informations d’erreur retournées par la requête.
Pour garantir l’ordre des opérations pour les requêtes, les requêtes individuelles peuvent être séquencées à l’aide de la propriété dependsOn .
En plus des opérations de séquencement et de dépendance, le traitement par lots JSON suppose un chemin de base et exécute les requêtes à partir d’un chemin relatif. Chaque élément de demande de lot est exécuté à partir des /v1.0/$batch points de terminaison OR /beta/$batch spécifiés. Cela peut présenter des différences significatives, car le point de /beta terminaison peut retourner une sortie supplémentaire qui peut NE PAS être retournée dans le point de /v1.0 terminaison.
Par exemple, exécutez les deux requêtes suivantes dans le Explorer Microsoft Graph.
- Interrogez le point de
/v1.0/$batchterminaison à l’aide de l’URL/me(copiez et collez la demande ci-dessous).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Utilisez maintenant la liste déroulante du sélecteur de version pour passer au beta point de terminaison et effectuer exactement la même demande.
Quelles sont les différences dans les résultats retournés ? Essayez d’autres requêtes pour identifier certaines des différences.
Outre le /v1.0 contenu de réponse différent des points de terminaison et /beta , il est important de comprendre les erreurs possibles lorsqu’une demande par lot est effectuée pour laquelle le consentement d’autorisation n’a pas été accordé. Par exemple, voici un élément de demande par lot pour créer un bloc-notes OneNote.
{
"id": 1,
"url": "/groups/65c5ecf9-3311-449c-9904-29a2c76b9a50/onenote/notebooks",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Meeting Notes"
}
}
Toutefois, si les autorisations de création de blocs-notes OneNote n’ont pas été accordées, la réponse suivante est reçue. Notez le code 403 (Forbidden) status et le message d’erreur qui indique que le jeton OAuth fourni n’inclut pas les étendues requises pour terminer l’action demandée.
{
"responses": [
{
"id": "1",
"status": 403,
"headers": {
"Cache-Control": "no-cache"
},
"body": {
"error": {
"code": "40004",
"message": "The OAuth token provided does not have the necessary scopes to complete the request.
Please make sure you are including one or more of the following scopes: Notes.ReadWrite.All,
Notes.Read.All (you provided these scopes: Group.Read.All,Group.ReadWrite.All,User.Read,User.Read.All)",
"innerError": {
"request-id": "92d50317-aa06-4bd7-b908-c85ee4eff0e9",
"date": "2018-10-17T02:01:10"
}
}
}
}
]
}
Chaque requête de votre lot retourne un code status et des résultats ou des informations d’erreur. Vous devez traiter chacune des réponses afin de déterminer la réussite ou l’échec des opérations de lot individuelles.
Créer un flux
Dans cet exercice, vous allez créer un flux pour utiliser le connecteur personnalisé que vous avez créé dans les exercices précédents pour créer et configurer une équipe Microsoft. Le flux utilise le connecteur personnalisé pour envoyer une requête POST afin de créer un groupe unifié Office 365, s’interrompt pendant un délai pendant la fin de la création du groupe, puis envoie une requête PUT pour associer le groupe à une équipe Microsoft.
En fin de compte, votre flux ressemblera à l’image suivante :
Ouvrez Microsoft Power Automate dans votre navigateur et connectez-vous avec votre compte d’administrateur de locataire Office 365. Choisissez Mes flux dans le volet de navigation gauche. Choisissez Nouveau, puis Instantané à partir de vide. Entrez Create Team pour Nom du flux, puis sélectionnez Déclencher manuellement un flux sous Choisir comment déclencher ce flux. Sélectionnez Créer.
Sélectionnez l’élément Déclencher manuellement un flux , puis choisissez Ajouter une entrée, sélectionnez Texte et entrez Name comme titre.
Choisissez Nouvelle étape et tapez Batch dans la zone de recherche. Ajoutez l’action Ms Graph Batch Connector . Choisissez les points de suspension et renommez cette action en Batch POST-groups.
Ajoutez le code suivant dans la zone de corps de texte de l’action.
{
"requests": [
{
"url": "/groups",
"method": "POST",
"id": 1,
"headers": { "Content-Type": "application/json" },
"body": {
"description": "REPLACE",
"displayName": "REPLACE",
"groupTypes": ["Unified"],
"mailEnabled": true,
"mailNickname": "REPLACE",
"securityEnabled": false
}
}
]
}
Remplacez chaque REPLACE espace réservé en sélectionnant la Name valeur du déclencheur manuel dans le menu Ajouter du contenu dynamique .
Choisissez Nouvelle étape, recherchez delay et ajoutez une action Retarder et configurez pendant 1 minute.
Choisissez Nouvelle étape et tapez Batch dans la zone de recherche. Ajoutez l’action Ms Graph Batch Connector . Choisissez les points de suspension et renommez cette action en Batch PUT-team.
Ajoutez le code suivant dans la zone de corps de texte de l’action.
{
"requests": [
{
"id": 1,
"url": "/groups/REPLACE/team",
"method": "PUT",
"headers": {
"Content-Type": "application/json"
},
"body": {
"memberSettings": {
"allowCreateUpdateChannels": true
},
"messagingSettings": {
"allowUserEditMessages": true,
"allowUserDeleteMessages": true
},
"funSettings": {
"allowGiphy": true,
"giphyContentRating": "strict"
}
}
}
]
}
Sélectionnez l’espace REPLACE réservé, puis expression dans le volet de contenu dynamique. Ajoutez la formule suivante à l’expression.
body('Batch_POST-groups').responses[0].body.id
Cette formule spécifie que nous voulons utiliser l’ID de groupe du résultat de la première action.
Choisissez Enregistrer, puis Tester pour exécuter le flux.
Conseil
Si vous recevez une erreur telle que The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template', l’expression est incorrecte et fait probablement référence à une action de flux qu’elle ne trouve pas. Vérifiez que le nom de l’action que vous référencez correspond exactement.
Choisissez la case d’option J’exécuterai l’action de déclencheur , puis choisissez Enregistrer & test. Choisissez Continuer dans la boîte de dialogue. Fournissez un nom sans espaces, puis choisissez Exécuter le flux pour créer une équipe.
Enfin, choisissez Terminé pour afficher le journal d’activité. Une fois le flux terminé, votre groupe Office 365 et votre équipe ont été configurés. Sélectionnez les éléments d’action Batch pour afficher les résultats des appels JSON Batch. Le outputs de l’action Batch PUT-team doit avoir un code status 201 pour une association d’équipe réussie similaire à l’image ci-dessous.
Étendre le flux
Le flux que vous avez créé dans l’exercice précédent utilise l’API $batch pour effectuer deux requêtes individuelles à Microsoft Graph. L’appel du $batch point de terminaison de cette façon offre un avantage et une certaine flexibilité, mais la véritable puissance du point de terminaison se produit lors de l’exécution $batch de plusieurs requêtes à Microsoft Graph en un seul $batch appel. Dans cet exercice, vous allez étendre l’exemple de création d’un groupe unifié et d’association d’une équipe afin d’inclure la création de plusieurs canaux par défaut pour l’équipe dans une seule $batch requête.
Ouvrez Microsoft Power Automate dans votre navigateur et connectez-vous avec votre compte d’administrateur de locataire Microsoft 365. Sélectionnez le flux que vous avez créé à l’étape précédente, puis choisissez Modifier.
Choisissez Nouvelle étape et tapez Batch dans la zone de recherche. Ajoutez l’action Ms Graph Batch Connector . Choisissez les points de suspension et renommez cette action en Batch POST-channels.
Ajoutez le code suivant dans la zone de corps de texte de l’action.
{
"requests": [
{
"id": 1,
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Marketing Collateral",
"description": "Marketing collateral and documentation."
}
},
{
"id": 2,
"dependsOn": [
"1"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Vendor Contracts",
"description": "Vendor documents, contracts, agreements and schedules."
}
},
{
"id": 3,
"dependsOn": [
"2"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "General Client Agreements",
"description": "General Client documents and agreements."
}
}
]
}
Notez que les trois requêtes ci-dessus utilisent la propriété dependsOn pour spécifier un ordre de séquence, et chacune exécute une requête POST pour créer un canal dans la nouvelle équipe.
Sélectionnez chaque instance de l’espace REPLACE réservé, puis sélectionnez Expression dans le volet de contenu dynamique. Ajoutez la formule suivante à l’expression.
body('Batch_PUT-team').responses[0].body.id
Choisissez Enregistrer, puis Tester pour exécuter le flux. Sélectionnez la case d’option Je vais effectuer l’action de déclencheur , puis choisissez Enregistrer & test. Entrez un nom de groupe unique dans le champ Nom sans espaces, puis choisissez Exécuter le flux pour exécuter le flux.
Une fois le flux démarré, choisissez le bouton Terminé pour afficher le journal d’activité. Une fois le flux terminé, la sortie finale de l’action Batch POST-channels a une réponse d’état HTTP 201 pour chaque canal créé.
Accédez à Microsoft Teams et connectez-vous avec votre compte d’administrateur de locataire Microsoft 365. Vérifiez que l’équipe que vous venez de créer s’affiche et inclut les trois canaux créés par la $batch requête.
Bien que l’action ci-dessus Batch POST-channels ait été implémentée dans ce didacticiel en tant qu’action distincte, les appels pour créer les canaux auraient pu être ajoutés en tant qu’appels supplémentaires dans l’action Batch PUT-team . Cela aurait créé l’équipe et tous les canaux dans un seul appel par lots. Essayez cela par vous-même.
Enfin, n’oubliez pas que les appels de traitement par lot JSON retournent un code de status HTTP pour chaque requête. Dans un processus de production, vous pouvez combiner le post-traitement des résultats avec une Apply to each action et valider que chaque réponse individuelle a un code de status 201 ou compenser les autres codes status reçus.
Félicitations !
Vous avez terminé le tutoriel Power Automate Microsoft Graph. Maintenant que vous disposez d’un connecteur personnalisé opérationnel qui appelle Microsoft Graph, vous pouvez expérimenter et ajouter de nouvelles fonctionnalités. Consultez la vue d’ensemble de Microsoft Graph pour voir toutes les données accessibles avec Microsoft Graph.
Commentaires
Veuillez fournir des commentaires sur ce didacticiel dans le référentiel GitHub.
Vous avez un défi avec cette section ? Si c'est le cas, faites-nous part de vos commentaires pour que nous puissions l'améliorer.