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. 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 plus d’informations sur les notifications enrichies, consultez Notifications enrichies.
- Notifications de cycle de vie : notifications qui alertent le client lorsqu’il est exposé à des notifications de modification manquantes 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.
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.
- Azure Event Grid (préversion). Pour plus d’informations, consultez Recevoir des notifications de modification via Azure Event Grid.
Gestion des abonnements
Les clients peuvent créer, renouveler et supprimer des abonnements. Lorsque l’abonnement est actif 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. Microsoft Graph envoie des notifications de modification dans une structure définie dans le type de ressource changeNotificationCollection.
Ressources prises en charge
Une application peut s’abonner aux modifications apportées aux ressources Microsoft Graph répertoriées dans le tableau.
Remarque
Les abonnements aux ressources marqués avec un astérisque (*) sont uniquement disponibles 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 y a 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 pour le travail ou l’établissement scolaire | 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. NOTE: La création et la suppression réversible de groupes déclenchent également le updatedchangeType. |
| 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} |
Pour plus d’informations, consultez alertes API de sécurité. |
| Approbations Teams | Modifications apportées à toutes les approbations dans un locataire : /solutions/approval/approvalItems |
Quotas maximaux d'abonnement : |
| Teams callRecord | Modifications apportées à tous les enregistrements d’appels : /communications/callRecords Modifications apportées aux enregistrements d’appels filtrés : /communications/callRecords?$filter={parameters} |
Pour plus d’informations, consultez Notifications de modification pour les enregistrements d’appels. Quotas maximaux d'abonnement : NOTE: La création d’enregistrements d’appel déclenche également le updatedchangeType. |
| CallRecording Teams | Tous les enregistrements d’un organization :communications/onlineMeetings/getAllRecordings Tous les enregistrements d’une réunion spécifique : communications/onlineMeetings/{onlineMeetingId}/recordings Enregistrement d’appel qui devient disponible dans une réunion organisée par un utilisateur spécifique : users/{id}/onlineMeetings/getAllRecordings Enregistrement d’appel qui devient disponible dans une réunion où une application Teams particulière est installée : appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Quotas maximaux d'abonnement : |
| Teams callTranscript | Toutes les transcriptions d’un organization :communications/onlineMeetings/getAllTranscripts Toutes les transcriptions d’une réunion spécifique : communications/onlineMeetings/{onlineMeetingId}/transcripts Transcription d’appel qui devient disponible dans une réunion organisée par un utilisateur spécifique : users/{id}/onlineMeetings/getAllTranscripts Transcription d’appel qui devient disponible dans une réunion où une application Teams particulière est installée : appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
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} Modifications apportées à une conversation spécifique avec le paramètre de requête notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean} Modifications apportées à toutes les conversations dans un organization où une application Teams particulière est installée : /appCatalogs/teamsApps/{id}/installedToChats Modifications apportées à toutes les conversations dont un utilisateur particulier fait partie : /users/{id}/chats Modifications apportées à toutes les conversations auxquelles un utilisateur particulier fait partie avec le paramètre de requête notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
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 Modifications apportées aux messages de conversation pour toutes les conversations dans un organization où une application Teams particulière est installée : /appCatalogs/teamsApps/{id}/installedToChats/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 dans un organization où une application Teams particulière est installée : /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Modifications apportées à l’appartenance à toutes les conversations : /chats/getAllMembers |
Quotas maximaux d'abonnement : |
| Teams onlineMeeting* | Modifications apportées à une réunion en ligne : /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
Ne prend pas en charge l’utilisation $select de pour retourner uniquement les propriétés sélectionnées. La notification enrichie se compose de toutes les propriétés du instance modifié. Un abonnement autorisé par application et par réunion en ligne. Pour plus d’informations, consultez Obtenir des notifications de modification pour les mises à jour des événements d’appel de réunion Microsoft Teams. |
| présenceTeams | Modifications apportées à la présence d’un seul utilisateur : /communications/presences/{id} Modifications apportées à la présence de plusieurs utilisateurs : /communications/presences?$filter=id in ({id},{id}...) |
L’abonnement pour la présence de plusieurs utilisateurs est limité à 650 utilisateurs distincts. Ne prend pas en charge l’utilisation $select de pour retourner uniquement les propriétés sélectionnées. La notification enrichie se compose de toutes les propriétés du instance modifié. Un abonnement autorisé par application et par utilisateur délégué. Pour plus d’informations, consultez Obtenir des notifications de modification pour les mises à jour de présence dans Microsoft Teams. |
| É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 : |
| Teams Shifts offerShiftRequest | Modifications apportées à toute demande de shift d’offre dans une équipe : /teams/{id}/schedule/offerShiftRequests |
Quotas maximaux d'abonnement : |
| Teams Shifts openShiftChangeRequest | Modifications apportées à toute demande de shift ouverte dans une équipe : /teams/{id}/schedule/openShiftChangeRequests |
Quotas maximaux d'abonnement : |
| Équipes Shifts shifts | Modifications apportées à n’importe quel changement dans une équipe : /teams/{id}/schedule/shifts |
Quotas maximaux d'abonnement : |
| Teams Shifts swapShiftsChangeRequest | Modifications apportées à toute demande de shift d’échange dans une équipe : /teams/{id}/schedule/swapShiftsChangeRequests |
Quotas maximaux d'abonnement : |
| Teams Shifts timeOffRequest | Modifications apportées à toute demande de congé dans une équipe : /teams/{id}/schedule/timeOffRequests |
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. NOTE: La création et la suppression réversible d’utilisateurs déclenchent également le updatedchangeType. |
Remarque
De nombreuses ressources ont des limites ou des quotas sur le nombre d’abonnements qui peuvent être effectués sur cette ressource. En cas de dépassement de cette limite, les tentatives de création d’un abonnement entraînent une 403 Forbidden réponse d’erreur.
La propriété message de la réponse d’erreur explique la limite qui a été dépassée.
Certaines de ces ressources prennent en charge les notifications enrichies (notifications avec des données de ressources). Pour plus d’informations sur les ressources qui prennent en charge les notifications enrichies, consultez Configurer des notifications de modification qui incluent des données de ressources.
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) |
| Approbations Teams | 43 200 minutes (moins de 30 jours) |
| Teams callRecord | 4 230 minutes (moins de trois jours) |
| CallRecording Teams | 4 320 minutes (trois jours) |
| Teams callTranscript | 4 320 minutes (trois jours) |
| Canal Teams | 4 320 minutes (trois jours) |
| Conversation Teams | 4 320 minutes (trois jours) |
| chatmessage Teams | 4 320 minutes (trois jours) |
| conversationMember Teams | 4 320 minutes (trois jours) |
| Teams onlineMeeting | 4 320 minutes (trois jours) |
| Équipe Teams | 4 320 minutes (trois jours) |
| Teams TeamsAppInstallation | 4 320 minutes (3 jours) |
| Teams Shifts offerShiftRequest | 360 minutes (6 heures) |
| Teams Shifts openShiftChangeRequest | 360 minutes (6 heures) |
| Équipes Shifts shifts | 360 minutes (6 heures) |
| Teams Shifts swapShiftsChangeRequest | 360 minutes (6 heures) |
| Teams Shifts timeOffRequest | 360 minutes (6 heures) |
| Conversation de groupe | 4 230 minutes (moins de trois jours) |
| OneDrive driveItem | 42 300 minutes (moins de 30 jours) |
| Liste SharePoint | 42 300 minutes (moins de 30 jours) |
| Message Outlook, événement, contact | 10 080 minutes (moins de sept jours) |
| Ressources d’utilisateur, de groupeet d’annuaire | 41 760 minutes (moins de 29 jours) |
| onlineMeeting | 4 230 minutes (moins de trois jours) |
| présence | 60 minutes (1 heure) |
| Imprimer imprimante | 4 230 minutes (moins de trois jours) |
| Imprimer printTaskDefinition | 4 230 minutes (moins de trois jours) |
| todoTask | 4 230 minutes (moins de trois 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 trois 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.
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 |
|---|---|---|
| alerte1 | Moins de 3 minutes | 5 minutes |
| Approbations | Moins de 10 secondes | 40 secondes |
| calendar | Less than 1 minute | 3 minutes |
| callRecord | Moins de 15 minutes | 60 minutes |
| callRecording | Moins de 10 secondes | 60 minutes |
| callTranscript | Moins de 10 secondes | 60 minutes |
| canal | Moins de 10 secondes | 60 minutes |
| conversation | Moins de 10 secondes | 60 minutes |
| chatMessage | Moins de 10 secondes | 1 minute |
| contact | Less than 1 minute | 3 minutes |
| conversation | Inconnu | Inconnu |
| conversationMember | Moins de 10 secondes | 60 minutes |
| driveItem | Less than 1 minute | 5 minutes |
| événement | Inconnu | Inconnu |
| groupe | Inconnu | Inconnu |
| liste | Less than 1 minute | 5 minutes |
| message | Less than 1 minute | 3 minutes |
| offerShiftRequest | Less than 1 minute | 60 minutes |
| onlineMeeting | Moins de 10 secondes | 1 minute |
| openShiftChangeRequest | Less than 1 minute | 60 minutes |
| présence | Moins de 10 secondes | 1 minute |
| imprimante | Less than 1 minute | 5 minutes |
| printTaskDefinition | Less than 1 minute | 5 minutes |
| shift | Less than 1 minute | 60 minutes |
| swapShiftsChangeRequest | Less than 1 minute | 60 minutes |
| équipe | Moins de 10 secondes | 60 minutes |
| teamsAppInstallation | Moins de 10 secondes | 60 minutes |
| timeOffRequest | Less than 1 minute | 60 minutes |
| todoTask | Moins de 2 minutes | 15 minutes |
| utilisateur | Inconnu | Inconnu |
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.
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