Partager via

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 créez des applications basées sur des événements qui répondent aux modifications des ressources en temps réel.

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.
  • Acheminer les événements vers plusieurs destinations à l’aide des fonctionnalité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 de nouvelle tentative intégrée et les files d’attente de lettres mortes garantissent une remise d’événements fiable.

Sources d’événements prises en charge

Le tableau suivant répertorie les sources d’événements pour lesquelles les événements sont disponibles via l’API Graph. Pour la plupart des ressources, les événements annonçant leur création, leur mise à jour et leur suppression sont pris en charge. Pour plus d’informations sur les ressources pour lesquelles les événements sont déclenchés pour les sources d’événements, consultez les ressources prises en charge par les notifications de modification 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
To Do Tâche à effectuer Événements Microsoft ToDo
Alertes de sécurité Alerte Événements sur les alertes de sécurité Microsoft
Impression cloud 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. La rubrique partenaire est automatiquement créée dans le cadre de la création de l’abonnement à l’API Graph. 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 dois-je m’abonner à des événements provenant de sources d’API Microsoft Graph via Event Grid ?

Outre l’abonnement aux événements de l’API Microsoft Graph via Event Grid, vous avez d’autres options pour recevoir des notifications similaires (et non 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 à l’aide d’un seul abonnement à l’API Graph et éviter de gérer plusieurs abonnements à l’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.UserCreated 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 le faire à l’aide d’un seul abonnement à l’API Graph si 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 transférer et gérer des événements de manière standard à l’aide de la norme de spécification CloudEvents de la CNCF (Cloud Native Computing Foundation).
  • Vous valeurz la prise en charge de l’extensibilité que CloudEvents fournit. 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 basées sur les événements adoptées par le secteur.

Autoriser les événements de l’API Graph dans votre rubrique 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

Remplissez ces conditions préalables générales avant d’implémenter votre application pour créer et renouveler des abonnements d’API Microsoft Graph :

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 les exemples avec une section d’instructions détaillées , vous devez lire toutes les sections de cet article, car elles contiennent des informations plus importantes relatives au transfert d’événements d’API Microsoft Graph à l’aide d’Event Grid.

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

Lorsque vous créez un abonnement API Graph, une rubrique partenaire est créée pour vous. Vous transmettez les informations suivantes dans le paramètre notificationUrl pour spécifier la rubrique partenaire à créer et à associer au nouvel abonnement API Graph :

  • Nom de la rubrique partenaire
  • Nom du groupe de ressources dans lequel la rubrique partenaire est créée
  • 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,Created",
    "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": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType : le type de modification des ressources pour lequel vous souhaitez recevoir des événements. Valeurs valides : Updated, Deleted et Created. 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>. L’emplacement (également appelé région Azure) name peut être obtenu en exécutant la commande az account list-locations . 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 : URI utilisé pour définir la rubrique partenaire à laquelle les événements microsoft.graph.subscriptionReauthorizationRequired sont envoyés. Cet événement signale à votre application que l’abonnement API Graph expire bientôt. L’URI suit le même modèle que notificationUrl décrit précédemment si vous utilisez Event Grid comme destination pour les événements de cycle de vie. Dans ce cas, la rubrique partenaire doit être la même que celle spécifiée dans notificationUrl.
  • resource : ressource qui génère des événements qui annoncent des changements d’état.
  • expirationDateTime : heure à laquelle l’abonnement expire et à laquelle le flux d’événements s’arrête. Il doit être au format spécifié dans RFC (Request for Change) 3339. Vous devez spécifier une heure d’expiration comprise dans la durée d’abonnement maximale autorisée par type de ressource.
  • État du client. Cette propriété est facultative. Sert à la vérification des appels à votre application de gestionnaire d’événements lors de la remise des événements. Pour plus d’informations, consultez Propriétés de l’abonnement à l’API Graph.

Important

  • Le noms 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 propriété lifecycleNotificationUrl, vous devez supprimer l’abonnement existant et créer un abonnement spécifiant 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 automatiser le processus de renouvellement, l’API Microsoft Graph prend en charge les événements de notifications de cycle de vie auxquels les applications peuvent s’abonner. Actuellement, tous les types de ressources de l’API Microsoft Graph prennent en charge microsoft.graph.subscriptionReauthorizationRequired, qui est envoyé lorsque l’une des conditions suivantes se produit :

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

Si l’abonnement à l’API Graph n’est pas renouvelé après son expiration, créez un abonnement d’API Graph. Reportez-vous à la même rubrique partenaire utilisée dans l’abonnement expiré tant qu’elle a expiré pendant 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 un autre nom de 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

Lors de la réception d’un événement microsoft.graph.subscriptionReauthorizationRequired, votre application doit renouveler l’abonnement API Graph en effectuant ces actions :

  1. Si vous avez fourni une clé secrète client dans la propriété clientState lorsque vous avez créé l’abonnement API Graph, cette clé secrète client est incluse dans l’événement. 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. Des informations supplémentaires sont fournies plus loin dans la section Exemples avec instructions détaillées.

  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": "2024-04-30T11:00:00.0000000Z"
}

      Le renouvellement peut échouer si l’application n’est plus autorisée à accéder à la ressource. L’application devra peut-être ensuite 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. Il est important d’être prêt à réautoriser régulièrement votre point de terminaison 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.

Lors du renouvellement et/ou de la réautorisation de votre abonnement API Graph, la même rubrique partenaire spécifiée lors de la création de l’abonnement est utilisée.

Lors de la spécification d’un nouvel expirationDateTime, vérifiez qu’il s’agit d’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 obtenir des exemples sur la façon de réautoriser votre abonnement API Graph à l’aide de l’un des langages pris en charge, consultez Requête de réautorisation de l’abonnement.

Pour obtenir des exemples sur la façon de renouveler et de réautoriser votre abonnement API Graph à l’aide de l’un des langages pris en charge, consultez Requête 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éer des abonnements API Graph. Pour renouveler un abonnement, vous pouvez appeler l’API Graph à l’aide des extraits de code fournis dans Procédure pour renouveler un abonnement API Graph.
  • Obtenir des jetons d’authentification pour les utiliser lors de l’appel de l’API Microsoft Graph.

Remarque

Il est possible de créer votre abonnement à l’API Graph à l’aide de l’Explorateur d’API Microsoft 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 ? E-mail ask-graph-and-grid@microsoft.com.

Contenu connexe

Suivez ces deux étapes pour configurer la réception d’événements d’API Microsoft Graph à l’aide d’Event Grid :

  • Last updated on