Recevoir des événements de modification de l’API Microsoft Graph via Azure Event Grid

L’API Microsoft Graph fournit des notifications de modification pour les ressources dans les services Microsoft 365, notamment Microsoft Entra ID, Teams, Outlook et OneDrive. En vous abonnant à ces événements via Azure Event Grid, vous pouvez créer des applications pilotées par événements qui répondent en temps réel aux changements de ressources.

Cet article explique comment :

  • Créez des abonnements d’API Microsoft Graph qui fournissent des événements aux rubriques des partenaires Azure Event Grid.
  • Gérez les cycles de vie des abonnements avec le renouvellement automatique.
  • Acheminez les événements vers plusieurs destinations en utilisant les capacités de filtrage et de routage d’Event Grid.

Azure Event Grid offre plusieurs avantages par rapport aux abonnements d’API Microsoft Graph traditionnels basés sur le webhook :

  • Routage simplifié : utilisez un seul abonnement d’API Graph pour envoyer des événements à plusieurs destinations.
  • Filtrage avancé : acheminer des types d’événements spécifiques vers différentes applications en fonction des propriétés d’événement.
  • Conformité aux normes : recevoir des événements au format CloudEvents pour une meilleure interopérabilité.
  • Fiabilité : la logique intégrée de nouvelle tentative ainsi que les files d’attente de messages non distribués assurent une livraison fiable des événements.

Sources d’événements prises en charge

Le tableau suivant liste les sources d’événements pour lesquelles vous pouvez obtenir des événements via API Graph. Pour la plupart des ressources, API Graph prend en charge les événements qui annoncent leur création, leur mise à jour et leur suppression. Pour obtenir des informations détaillées sur les ressources qui génèrent des événements pour les sources d’événement, consultez les ressources prises en charge par les notifications de changement de l’API Microsoft Graph.

Source d’événement Microsoft Ressources Types d’événement disponibles
Microsoft Entra ID (système d'identification de Microsoft) Utilisateur, Groupe Types d’événements Microsoft Entra ID
Microsoft Outlook Événement (réunion du calendrier), Message (e-mail), Contact Types d’événements Microsoft Outlook
Microsoft Teams Message instantané, Enregistrement d’appel (réunion) Types d’événements Microsoft Teams
OneDrive Élément Drive Événements Microsoft OneDrive
Microsoft SharePoint Liste Événements Microsoft SharePoint
À faire Tâche à effectuer Événements Microsoft ToDo
Alertes de sécurité Alerte Événements d'alertes de sécurité Microsoft
Impression en nuage Imprimante, Définition de tâche d’impression Événements d’impression Microsoft Cloud
Microsoft Conversations Conversation Événements de conversation de groupe Microsoft 365

Créez un abonnement à l’API Microsoft Graph pour permettre aux événements d’API Graph de passer à une rubrique partenaire. API Graph crée automatiquement le sujet partenaire lorsque vous créez l’abonnement. Utilisez cette rubrique partenaire pour créer des abonnements aux événements pour envoyer vos événements à l’un des gestionnaires d’événements pris en charge qui répondent le mieux à vos besoins pour traiter les événements.

Important

Si vous n’êtes pas familiarisé avec la fonctionnalité Événements partenaires , consultez la vue d’ensemble des événements partenaires.

Pourquoi s’abonner aux événements des sources Microsoft API Graph via Event Grid ?

En plus de vous abonner aux événements Microsoft API Graph via Event Grid, vous avez d’autres options pour recevoir des notifications similaires (pas des événements). Utilisez l’API Microsoft Graph pour remettre des événements à Event Grid si vous remplissez au moins l’une des conditions suivantes :

  • Vous développez une solution pilotée par les événements qui utilise des événements de Microsoft Entra ID, Outlook ou Teams pour réagir aux modifications des ressources. Vous avez besoin du modèle robuste piloté par les événements et des fonctionnalités d’abonnement publiées par Event Grid. Pour obtenir une vue d’ensemble d’Event Grid, consultez Concepts d’Event Grid.
  • Vous souhaitez utiliser Event Grid pour acheminer les événements vers plusieurs destinations en utilisant un seul abonnement API Graph, et éviter de gérer plusieurs abonnements API Graph.
  • Vous devez router des événements vers différentes applications en aval, webhooks ou services Azure en fonction de certaines propriétés dans l’événement. Par exemple, vous pouvez acheminer des types d’événements tels que Microsoft.Graph.UserUpdated et Microsoft.Graph.UserDeleted vers une application spécialisée qui traite l’intégration et la désactivation des utilisateurs. Vous pouvez également envoyer des événements Microsoft.Graph.UserUpdated à une autre application qui synchronise les informations sur les contacts, par exemple. Vous pouvez y parvenir en utilisant un seul abonnement API Graph lorsque vous utilisez Event Grid comme destination de notification. Pour plus d’informations, consultez filtrage d’événements et gestionnaires d’événements.
  • L’interopérabilité est importante pour vous. Vous souhaitez transmettre et gérer les événements de manière standard en utilisant la norme de spécification CloudEvents de Cloud Native Computing Foundation (CNCF).
  • Vous bénéficiez de la prise en charge de l’extensibilité apportée par CloudEvents. Par exemple, pour suivre les événements entre les systèmes conformes, utilisez le suivi distribué de l’extension CloudEvents. En savoir plus sur les extensions CloudEvents.
  • Vous utilisez des approches éprouvées, axées sur les événements, que l’industrie adopte.

Activer la transmission des événements de l'API Graph vers votre sujet partenaire

Demandez à l’API Microsoft Graph de transférer des événements à une rubrique partenaire Event Grid en créant un abonnement à l’API Graph à l’aide des kits de développement logiciel (SDK) de l’API Microsoft Graph et en suivant les étapes décrites dans les liens vers des exemples fournis dans cette section. Pour plus d’informations sur la prise en charge disponible dans le kit SDK, consultez Langages pris en charge pour le kit SDK de l’API Microsoft Graph.

Conditions préalables générales

Avant de mettre en œuvre votre application pour créer et renouveler des abonnements Microsoft API Graph, assurez-vous de remplir ces prérequis généraux :

Vous trouverez d’autres prérequis propres au langage de programmation de votre choix et à l’environnement de développement que vous utilisez dans les liens d’exemples d’API Microsoft Graph dans une section plus loin dans cet article.

Important

Bien que des instructions détaillées pour implémenter votre application se trouvent dans la section exemples avec instructions détaillées, lisez toutes les sections de cet article car elles contiennent des informations plus importantes concernant l’acheminement des événements Microsoft API Graph à l’aide de la grille d’événements.

Procédure pour créer un abonnement API Microsoft Graph

Lorsque vous créez un abonnement API Graph, le système crée un sujet partenaire pour vous. Vous passez les informations suivantes dans le paramètre notificationUrl pour spécifier le sujet partenaire à créer et à associer avec la nouvelle adhésion API Graph :

  • Nom de la rubrique partenaire
  • Nom du groupe de ressources pour le sujet partenaire
  • Région (localisation)
  • Abonnement Azure

Ces exemples de code montrent comment créer un abonnement d’API Graph. Ils incluent des exemples de création d’un abonnement pour recevoir des événements de tous les utilisateurs d’un locataire Microsoft Entra ID lorsqu’ils sont créés, mis à jour ou supprimés.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2026-08-31T00:00:00Z",
    "clientState": "secretClientValue"
}

  • changeType : le type de modification des ressources pour lequel vous souhaitez recevoir des événements. Valeurs valides : Updated et Deleted (Created n'est pas prise en charge par API Graph ; consultez la documentation de API Graph pour plus de détails). Vous pouvez spécifier une ou plusieurs de ces valeurs séparées par des virgules.

  • notificationUrl : URI utilisé pour définir la rubrique partenaire à laquelle les événements sont envoyés. Il doit être conforme au modèle suivant : EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>. Pour obtenir la localisation (également appelée région Azure), nameexécutez la az account list-locations commande. N’utilisez pas de nom d’affichage de localisation. Par exemple, n’utilisez pas USA Centre-Ouest. Utilisez westcentralus à la place.

    az account list-locations

  • lifecycleNotificationUrl: une URI utilisée pour définir le sujet partenaire vers lequel microsoft.graph.subscriptionReauthorizationRequired les événements sont envoyés. Cet événement signale à votre application que l’abonnement API Graph expire bientôt. L’URI suit le même schéma que notificationUrl décrit précédemment si vous utilisez Event Grid comme destination pour les événements du cycle de vie. Dans ce cas, la rubrique partenaire doit être la même que celle spécifiée dans notificationUrl.

  • resource: la ressource qui génère des événements annonçant des changements d’état.

  • expirationDateTime: le délai d’expiration de l’abonnement et de l’arrêt du flux des événements. Il doit respecter le format spécifié dans la Demande de commentaires (RFC) 3339. Vous devez spécifier un délai d’expiration qui correspond à la durée maximale d’abonnement autorisée par type de ressource.

  • clientState: utilisez cette propriété optionnelle pour vérifier les appels vers votre application gestionnaire d’événements lors de la livraison d’événements. Pour plus d’informations, consultez Propriétés de l’abonnement à l’API Graph.

Important

  • Le nom de la rubrique partenaire doit être unique dans la même région Azure. Chaque combinaison locataire/ID d’application peut créer jusqu’à 10 rubriques de partenaires uniques.

  • Tenez compte de certaines limites de service des ressources d’API Graph lors du développement de votre solution.

  • Les abonnements API Graph existants sans propriété lifecycleNotificationUrl ne reçoivent pas d’événements de cycle de vie. Pour ajouter la lifecycleNotificationUrl propriété, supprimez l’abonnement existant et créez un nouvel abonnement qui spécifie la propriété lors de la création de l’abonnement.

Après avoir créé un abonnement API Graph, vous disposez d’une rubrique partenaire créée sur Azure.

Renouveler un abonnement API Microsoft Graph

Renouvelez l’abonnement à l’API Graph avant d’expirer pour éviter d’arrêter le flux d’événements. Pour aider à automatiser le processus de renouvellement, Microsoft API Graph prend en charge les événements de notification du cycle de vie auxquels les applications peuvent s’abonner. Actuellement, tous les types de ressources Microsoft API Graph prennent en charge l’événementmicrosoft.graph.subscriptionReauthorizationRequired, qui est envoyé lorsque l’une des conditions suivantes survient :

  • Le jeton d’accès est sur le point d’expirer.
  • L’abonnement API Graph est sur le point d’expirer.
  • Un administrateur du tenant a révoqué les permissions de votre application pour lire une ressource.

Si l’abonnement à l’API Graph n’est pas renouvelé après son expiration, créez un abonnement d’API Graph. Vous pouvez utiliser la même rubrique partenaire que celle utilisée pour l’abonnement expiré, à condition que l’abonnement ait expiré depuis moins de 30 jours. Si l’abonnement API Graph a expiré depuis plus de 30 jours, vous ne pouvez pas réutiliser votre rubrique partenaire existante. Dans ce cas, vous devez spécifier le nom d’une autre rubrique partenaire. En guise d’alternative, vous pouvez supprimer la rubrique partenaire existante pour créer une rubrique partenaire portant le même nom lors de la création de l’abonnement API Graph.

Procédure pour renouveler un abonnement API Microsoft Graph

Lorsque votre application reçoit un microsoft.graph.subscriptionReauthorizationRequired événement, elle doit renouveler l’abonnement API Graph :

  1. Si vous avez fourni un secret client dans la propriété clientState lors de la création de l’abonnement API Graph, l’événement inclut ce secret client. Vérifiez que le clientState de l’événement correspond à la valeur utilisée lors de la création de l’abonnement API Graph.

  2. Vérifiez que l’application dispose d’un jeton d’accès valide pour effectuer l’étape suivante. Les prochains exemples avec la section des instructions détaillées fournissent plus d’informations.

  3. Appelez l’une des deux API suivantes. Si l’appel d’API réussit, le flux de notification de modification reprend.

    • Appelez l’action /reauthorize pour réautoriser l’abonnement sans prolonger sa date d’expiration.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • Effectuez une action « renouveler » régulière pour réautoriser et renouveler l’abonnement en même temps.

      PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-Type: application/json

{
   "expirationDateTime": "2026-09-30T11:00:00.0000000Z"
}

      Le renouvellement peut échouer si l’application n’est plus autorisée à accéder à la ressource. L’application pourrait alors devoir obtenir un nouveau jeton d’accès pour réautoriser un abonnement.

Les défis d’autorisation ne remplacent pas la nécessité de renouveler un abonnement avant son expiration. Les cycles de vie des jetons d’accès et de l’expiration de l’abonnement ne sont pas les mêmes. Votre jeton d’accès peut expirer avant votre abonnement. Préparez-vous à réautoriser régulièrement votre endpoint pour actualiser votre jeton d’accès. La réautorisation de votre point de terminaison ne renouvelle pas votre abonnement. Toutefois, le renouvellement de votre abonnement réautorise également votre point de terminaison.

Lorsque vous renouvelez ou réautorisez votre abonnement API Graph, il utilise le même sujet partenaire que celui que vous avez spécifié lors de la création de l’abonnement.

Lorsque vous spécifiez une nouvelle date d’expirationHeure, assurez-vous qu’elle se situe au moins trois heures à partir de l’heure actuelle. Autrement, votre application risque de recevoir des événements microsoft.graph.subscriptionReauthorizationRequired peu après le renouvellement.

Pour des exemples de comment réautoriser votre abonnement API Graph en utilisant l’une des langues prises en charge, voir demande de réautorisation d’abonnement.

Pour des exemples de comment renouveler et réautoriser votre abonnement API Graph en utilisant l’une des langues prises en charge, voir demande de mise à jour de l’abonnement.

Exemples avec instructions détaillées

La documentation de l’API Microsoft Graph fournit des exemples de code avec des instructions pour :

  • Configurer votre environnement de développement avec des instructions spécifiques en fonction du langage que vous utilisez. Les instructions expliquent également comment obtenir un locataire Microsoft 365 à des fins de développement.
  • Créez un abonnement API Graph. Pour renouveler un abonnement, appelez l’API Graph en utilisant les extraits de code dans Comment renouveler un abonnement API Graph.
  • Obtenir des jetons d’authentification pour les utiliser lors de l’appel de l’API Microsoft Graph.

Remarque

Vous pouvez créer votre abonnement API Graph en utilisant l’explorateur Microsoft API Graph. Vous devez toujours utiliser les exemples pour d’autres aspects importants de votre solution, tels que l’authentification et la réception d’événements.

Des exemples d’applications web sont disponibles pour les langages suivants :

  • Exemple de code C#. Il s’agit d’un exemple à jour qui illustre comment créer et renouveler des abonnements API Graph, et vous guide tout au long des étapes permettant d’activer le flux d’événements.
  • Exemple Java
  • exempleNode.js.

Important

Vous devez activer votre rubrique partenaire créée dans le cadre de la création de votre abonnement API Graph. Vous devez également créer un abonnement aux événements Event Grid à votre application web pour recevoir des événements. À cette fin, vous utilisez l’URL configurée dans votre application web pour recevoir des événements en tant que point de terminaison de webhook dans votre abonnement aux événements.

Important

Vous avez besoin d’un exemple de code pour une autre langue ou avez des questions ? Envoyez un courrier électronique à ask-graph-and-grid@microsoft.com.

Contenu connexe

Pour recevoir des événements Microsoft API Graph via Event Grid, complétez ces deux étapes :

  • Last updated on