Configurer des notifications pour les modifications apportées aux données de ressource
Les notifications de modification permettent aux applications de recevoir des alertes lorsqu’une ressource Microsoft Graph les intéresse; c’est-à-dire créé, mis à jour ou supprimé. Microsoft Graph envoie des notifications au point de terminaison client spécifié, et le service client traite les notifications en fonction des besoins de l’entreprise. Par exemple, le service peut extraire plus de données, mettre à jour son cache et ses vues, etc.
Pourquoi recevoir des notifications de modification ?
Les notifications de modification suivent un modèle piloté par les événements où les clients reçoivent des alertes lorsque des modifications se produisent au lieu d’interroger Microsoft Graph. Selon votre logique métier, les notifications de modification sont appropriées dans les cas suivants :
- Vous vous abonnez à une ressource qui change fréquemment.
- Vous devez réagir aux changements en quasi-temps réel.
- Vous souhaitez éviter d’interroger fréquemment Microsoft Graph, ce qui peut vous amener à atteindre les limites de limitation.
Types de notifications de modification
Microsoft Graph prend en charge trois types de notifications de modification :
- Notifications de base : notifications de modification qui ne contiennent pas de données de ressource autres que l’ID de la ressource modifiée. Toutes les ressources Microsoft Graph prennent en charge les notifications de base. Lorsqu’une application reçoit une notification de base, le service peut utiliser l’ID pour interroger l’objet modifié.
- Notifications enrichies : notifications de modification qui incluent les données de ressource de l’objet modifié. Pour obtenir la liste des ressources Microsoft Graph qui prennent en charge les notifications enrichies, consultez ressources prises en charge.
- Notifications de cycle de vie : notifications qui alertent le client lorsqu’il est exposé à un risque de notification de modification manquante en raison du cycle de vie de son abonnement. Pour plus d’informations sur les notifications de cycle de vie, consultez Notifications de cycle de vie.
Ressources prises en charge
Une application peut s’abonner aux modifications apportées aux ressources Microsoft Graph répertoriées dans le tableau, ce qui indique également les limites qui s’appliquent aux abonnements aux ressources. Quand une limite est dépassée, les tentatives de création d’un abonnement entraînent une réponse d’erreur 403 Forbidden . La propriété message de la réponse d’erreur explique la limite qui a été dépassée.
Remarque
Les abonnements aux ressources marqués d’un astérisque (*) sont disponibles uniquement sur le point de /beta terminaison.
| Resource | Chemins d’accès aux ressources pris en charge | Limitations |
|---|---|---|
| Imprimante pour impression cloud | Modifications lorsqu’un travail d’impression est prêt à être téléchargé (événement jobFetchable) : /print/printers/{id}/jobs |
- |
| Impression Cloud printTaskDefinition | Change lorsqu’il existe un travail valide dans la file d’attente (événement jobStarted) : /print/printtaskdefinition/{id}/tasks |
- |
| driveItem sur OneDrive (personnel) | Modifications apportées au contenu dans la hiérarchie d’un dossier : /users/{id}/drive/root |
- |
| driveItem sur OneDrive Entreprise | Modifications apportées au contenu dans la hiérarchie du dossier racine : /drives/{id}/root , /users/{id}/drive/root |
- |
| groupe | Modifications apportées à tous les groupes : /groups Modifications apportées à un groupe spécifique : /groups/{id} Modifications apportées aux propriétaires d’un groupe spécifique : /groups/{id}/owners Modifications apportées aux membres d’un groupe spécifique : /groups/{id}/members |
Quotas maximaux d'abonnement : Non pris en charge pour les locataires Azure AD B2C. Problème connu pour l’abonnement changeType. |
| Une liste sous un site SharePoint | Modifications apportées au contenu de la liste : /sites/{site-id}/lists/{list-id} |
- |
| Conversation de groupe Microsoft 365 | Modifications apportées aux conversations d’un groupe : groups/{id}/conversations |
- |
| message Outlook | Modifications apportées à tous les messages dans la boîte aux lettres d’un utilisateur : /users/{id}/messages , /me/messages Modifications apportées aux messages dans la boîte de réception d’un utilisateur : /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages |
Un maximum de 1 000 abonnements actifs par boîte aux lettres pour toutes les applications est autorisé. |
| événement Outlook | Modifications apportées à tous les événements dans la boîte aux lettres d’un utilisateur : /users/{id}/events , /me/events |
Un maximum de 1 000 abonnements actifs par boîte aux lettres pour toutes les applications est autorisé. |
| contact personnel Outlook | Modifications apportées à tous les contacts personnels dans la boîte aux lettres d’un utilisateur : /users/{id}/contacts , /me/contacts |
Un maximum de 1 000 abonnements actifs par boîte aux lettres pour toutes les applications est autorisé. |
| Alerte de sécurité | Modifications apportées à une alerte spécifique : /security/alerts/{id} Modifications apportées aux alertes filtrées : /security/alerts/?$filter={parameters} |
- |
| Teams callRecord | Modifications apportées à tous les enregistrements d’appels : /communications/callRecords |
Quotas maximaux d'abonnement : |
| Conversation Teams | Modifications apportées à n’importe quelle conversation dans le locataire : /chats Modifications apportées à une conversation spécifique : /chats/{id} |
Quotas maximaux d'abonnement : |
| chatmessage Teams | Modifications apportées aux messages de conversation dans tous les canaux de toutes les équipes : /teams/getAllMessages Modifications apportées aux messages de conversation dans un canal spécifique : /teams/{id}/channels/{id}/messages Modifications apportées aux messages de conversation dans toutes les conversations : /chats/getAllMessages Modifications apportées aux messages de conversation dans une conversation spécifique : /chats/{id}/messages Modifications apportées aux messages de conversation dans toutes les conversations dont un utilisateur particulier fait partie : /users/{id}/chats/getAllMessages |
Quotas maximaux d'abonnement : |
| Canal Teams | Modifications apportées aux canaux dans toutes les équipes : /teams/getAllChannels Modifications apportées au canal dans une équipe spécifique : /teams/{id}/channels |
Quotas maximaux d'abonnement : |
| conversationMember Teams | Modifications apportées à l’appartenance à une équipe spécifique : /teams/{id}/members Modifications apportées à l’appartenance à tous les canaux d’une équipe spécifique : teams/{id}/channels/getAllMembers Modifications apportées à l’appartenance à une conversation spécifique : /chats/{id}/members Modifications apportées à l’appartenance à toutes les conversations : /teams/getAllMembers |
Quotas maximaux d'abonnement : |
| Teams onlineMeeting * | Modifications apportées à une réunion en ligne : /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl} |
|
| Présence de Teams * | Modifications apportées à la présence d’un seul utilisateur : /communications/presences/{id} Modifications apportées à plusieurs présences d’utilisateurs : /communications/presences?$filter=id in ({id},{id}...) |
|
| Équipe Teams | Modifications apportées à n’importe quelle équipe dans le locataire : /teams Modifications apportées à une équipe spécifique : /teams/{id} |
Quotas maximaux d'abonnement : |
| todoTask | Modifications apportées à toutes les tâches d’une liste de tâches spécifique : /me/todo/lists/{todoTaskListId}/tasks |
- |
| utilisateur | Modifications apportées à tous les utilisateurs : /users Modifications apportées à un utilisateur spécifique : /users/{id} |
Quotas maximaux d'abonnement : Non pris en charge pour les comptes Microsoft personnels tels que outlook.com. Non pris en charge pour les locataires Azure AD B2C. Problème connu pour l’abonnement changeType. |
Les ressources suivantes prennent en charge les notifications enrichies (notifications avec des données de ressources) :
- événementOutlook
- messageOutlook
- Recherche descontacts personnels Outlook
- Conversation Teams
- chatMessage Teams
- Canal Teams
- conversationMember Teams
- Teams onlineMeeting *
- Présence de Teams *
- Équipe Teams
Réception de notifications de modification
Microsoft Graph peut envoyer des notifications de modification aux clients via les canaux suivants.
- Webhooks. Pour plus d’informations, consultez Recevoir des notifications de modification via des webhooks.
- Azure Event Hubs. Pour plus d’informations, consultez Recevoir des notifications de modification via Azure Event Hubs.
Durée de vie de l’abonnement
Les abonnements ont une durée de vie limitée. Les applications doivent renouveler leurs abonnements avant l’heure d’expiration ; Sinon, ils doivent créer un abonnement. Les applications peuvent également annuler leur abonnement à tout moment pour ne plus recevoir de notifications de modifications.
Le tableau suivant indique les durées d’expiration maximales des abonnements par ressource dans Microsoft Graph.
| Resource | Délai d’expiration maximal |
|---|---|
| Alerte de sécurité | 43 200 minutes (moins de 30 jours) |
| Teams callRecord | 4 230 minutes (moins de 3 jours) |
| Canal Teams | 60 minutes (1 heure) |
| Conversation Teams | 60 minutes (1 heure) |
| Teams chatMessage | 60 minutes (1 heure) |
| conversationMember Teams | 60 minutes (1 heure) |
| Teams onlineMeeting | 4 320 minutes (3 jours) |
| Équipe Teams | 60 minutes (1 heure) |
| Conversation de groupe | 4 230 minutes (moins de 3 jours) |
| OneDrive driveItem | 42 300 minutes (moins de 30 jours) |
| Liste SharePoint | 42 300 minutes (moins de 30 jours) |
| Message Outlook, événement, contact | 4 230 minutes (moins de 3 jours) |
| Ressources d’utilisateur, de groupeet d’annuaire | 41 760 minutes (moins de 29 jours) |
| onlineMeeting | 4 230 minutes (moins de 3 jours) |
| présence | 60 minutes (1 heure) |
| Imprimer imprimante | 4 230 minutes (moins de 3 jours) |
| Imprimer printTaskDefinition | 4 230 minutes (moins de 3 jours) |
| todoTask | 4 230 minutes (moins de 3 jours) Les webhooks pour cette ressource sont disponibles uniquement dans le point de terminaison global et non dans les clouds nationaux. |
| baseTask (déconseillé) | 4 230 minutes (moins de 3 jours) |
Note:les applications existantes et nouvelles ne doivent pas dépasser la valeur prise en charge. À l’avenir, les demandes pour créer ou renouveler un abonnement au-delà de la valeur maximale peut échouer.
Gestion des abonnements
Les clients peuvent créer, renouveler et supprimer des abonnements. Ensuite, lorsque l’abonnement est valide et que des modifications se produisent dans la ressource abonnée, Microsoft Graph envoie des notifications de modification au point de terminaison de notification spécifié.
Vous gérez l’abonnement à l’aide du type de ressource d’abonnement et de ses méthodes associées. Lorsque l’abonnement est valide et que des modifications se produisent dans la ressource abonnée, Microsoft Graph envoie une notification de modification dans une structure définie dans le type de ressource changeNotificationCollection.
Pour plus d’informations sur la gestion des abonnements pour les différents canaux de distribution à l’aide de Microsoft Graph, consultez les articles suivants.
- Recevoir une notification de modification via des webhooks.
- Recevoir une notification de modification via Azure Event Hubs
Exemples de code
Les exemples de code suivants sont disponibles sur GitHub.
- Module de formation Microsoft Graph – Utilisation des notifications de modification et du suivi des modifications avec Microsoft Graph
- Exemple de Webhooks Microsoft Graph pour Node.js
- Exemple de Webhooks Microsoft Graph pour ASP.NET Core
- Exemple de Webhooks Microsoft Graph pour Java Spring
Latence
Le tableau suivant indique le temps de latence à prévoir entre un événement survenant dans le service et la remise de la notification de changement.
| Ressource | Latence moyenne | Latence maximale |
|---|---|---|
| [alerte] [] 1 | Moins de 3 minutes | 5 minutes |
| [callRecord] [] | Moins de 15 minutes | 60 minutes |
| [channel] [] | Moins de 10 secondes | 60 minutes |
| [conversation] [] | Moins de 10 secondes | 60 minutes |
| [chatMessage] [] | Moins de 10 secondes | 1 minute |
| [contact] [] | Inconnu | Inconnu |
| [conversation] [] | Inconnu | Inconnu |
| [conversationMember] [] | Moins de 10 secondes | 60 minutes |
| [driveItem] [] | Less than 1 minute | 5 minutes |
| [événement] [] | Inconnu | Inconnu |
| [groupe] [] | Moins de 2 minutes | 15 minutes |
| [list] [] | Less than 1 minute | 5 minutes |
| [message] [] | Inconnu | Inconnu |
| [onlineMeeting] [] | Moins de 10 secondes | 1 minute |
| [présence] [] | Moins de 10 secondes | 1 minute |
| [printer] [] | Less than 1 minute | 5 minutes |
| [printTaskDefinition] [] | Less than 1 minute | 5 minutes |
| [team] [] | Moins de 10 secondes | 60 minutes |
| [todoTask][] | Moins de 2 minutes | 15 minutes |
| [utilisateur] [] | Moins de 2 minutes | 15 minutes |
1 La latence fournie pour la ressource d’alerte s’applique uniquement après la création de l’alerte. Il n’inclut pas le temps nécessaire à une règle pour créer une alerte à partir des données.
Ressources de déploiement
- Recevoir des notifications de modification via des webhooks
- Recevoir des notifications de modification via Azure Event Hubs
- Notifications enrichies (notifications avec données de ressources)
- Notifications de cycle de vie
- Tutoriels