Share via

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

  • Article

Cet article décrit la marche à suivre pour s’abonner aux événements publiés par l’API Microsoft Graph. 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 des événements sont déclenchés pour des sources d’événements, consultez 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 Utilisateur, Groupe Types d’événements Microsoft Entra
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é Alert É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

Vous créez un abonnement à l’API Microsoft Graph pour permettre aux événements de l’API Graph de passer à une rubrique partenaire. La rubrique partenaire est automatiquement créée pour vous dans le cadre de la création de l’abonnement à l’API Graph. Vous 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’avez pas l’habitude d’utiliser la fonctionnalité Événements partenaires, consultez 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 la possibilité de s’abonner aux événements de l’API Microsoft Graph via Event Grid, vous disposez d’autres options par le biais desquelles vous pouvez recevoir des notifications similaires (et non des événements). Envisagez d’utiliser l’API Microsoft Graph pour remettre des événements à Event Grid si vous avez au moins l’une des exigences suivantes :

  • Vous développez une solution, pilotée par les événements, qui nécessite des événements issus de Microsoft Entra ID, d’Outlook, de Teams, etc. pour réagir aux modifications de la ressource. Vous avez besoin du modèle d’événement robuste et des fonctionnalités d’abonnement aux publications fournis 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 acheminer des événements vers différents webhooks, services Azure ou applications en aval en fonction de certaines des propriétés de 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 aimez la prise en charge de l’extensibilité fournie par CloudEvents. Par exemple, si vous souhaitez suivre des événements sur divers systèmes conformes, utilisez l’extension de suivi distribué de CloudEvents. En savoir plus sur d’autres extensions CloudEvents.
  • Vous souhaitez utiliser des approches éprouvées pilotées par les événements adoptées par l’industrie.

Autoriser les événements de l’API Graph dans votre rubrique partenaire

Vous 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

Vous devez respecter ces prérequis généraux 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 la section Exemples avec instructions détaillées, vous devez lire toutes les sections de cet article, car elles contiennent des informations supplémentaires 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 API Graph. Ils fournissent 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

Votre application doit renouveler l’abonnement API Graph avant son expiration afin d’éviter l’arrêt du flux d’événements. Pour vous aider à automatiser le processus de renouvellement, l’API Microsoft Graph prend en charge les événements de notifications de cycle de vie auxquels votre application peut 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 vous n’avez pas renouvelé votre abonnement API Graph après son expiration, vous devez en créer un nouveau. Vous pouvez faire référence à la même rubrique partenaire que celle utilisée dans votre abonnement qui a expiré, tant qu’il a 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 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, celui-ci doit être postérieur à l’heure actuelle d’au moins trois heures. 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 API Graph à l’aide de l’Afficheur 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
    • GraphAPIController contient un exemple de code pour créer, supprimer et renouveler un abonnement API Graph. Il doit être utilisé avec l’exemple d’application Java.
  • Exemple NodeJS.

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. Étapes suivantes pour plus d’informations.

Important

Vous avez besoin d’un exemple de code pour un autre langage ou vous avez des questions ? Envoyez-nous un e-mail à l’adresse ask-graph-and-grid@microsoft.com.

Étapes suivantes

Suivez les instructions des deux étapes suivantes pour terminer la configuration afin de recevoir des événements d’API Microsoft Graph à l’aide d’Event Grid :

Autres liens utiles :