Configurer des notifications pour les modifications apportées aux données de ressource

  • Article

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.

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.

Ressource 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 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 :
  • Par application (pour tous les locataires combinés) : 50 000 abonnements au total.
  • Par locataire (pour toutes les applications combinées) : 1 000 abonnements au total sur toutes les applications.
  • Par combinaison d’application et de locataire : 100 abonnements au total.

    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é.
    Teams callRecord Modifications apportées à tous les enregistrements d’appels : /communications/callRecords Quotas maximaux d'abonnement :
  • Par organization : 100 abonnements au total.

    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 :
  • Par application et combinaison de réunion en ligne : 1
  • Par combinaison d’application et d’utilisateur : 1
  • Par utilisateur (pour les enregistrements de suivi des abonnements dans tous les onlineMeetings organisés par l’utilisateur) : 10 abonnements.
  • Par organization : 10 000 abonnements au total.
    		•
    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 :
  • Par application et combinaison de réunion en ligne : 1
  • Par combinaison d’application et d’utilisateur : 1
  • Par utilisateur (pour les transcriptions de suivi des abonnements dans tous les onlineMeetings organisés par l’utilisateur) : 10 abonnements.
  • Par organization : 10 000 abonnements au total.
    		•
    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 à toutes les conversations dans un organization où une application Teams particulière est installée :/appCatalogs/teamsApps/{id}/installedToChats    		 Quotas maximaux d'abonnement :
  • Par combinaison d’application et de conversation : 1 abonnement.
  • Par organization : 10 000 abonnements au total.
    		•
    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 :
  • Par application et canal ou combinaison de conversation : 1 abonnement.
  • Par utilisateur (pour les abonnements suivi des messages de conversation dans toutes les conversations dont l’utilisateur fait partie) : 10 abonnements.
  • Par organization : 10 000 abonnements au total.
    		•
    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 :
  • Par combinaison d’application et d’équipe : 1 abonnement.
  • Par organization : 10 000 abonnements au total.
    		•
    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 :
  • Par combinaison d’application et d’équipe : 1 abonnement.
  • Par organization : 10 000 abonnements au total.
    		•
    Teams onlineMeeting* Modifications apportées à une réunion en ligne : /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    présenceTeams 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 :
  • Par combinaison d’application et d’équipe : 1 abonnement.
  • Par organization : 10 000 abonnements au total.
    		•
    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 :
  • Par application (pour tous les locataires combinés) : 50 000 abonnements au total.
  • Par locataire (toutes applications combinées) : 1000 abonnements au total pour toutes les applications
  • Par combinaison d’application et de locataire : 100 abonnements au total.

    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)
    Teams callRecord 4 230 minutes (moins de 3 jours)
    CallRecording Teams 4 320 minutes (3 jours)
    Teams callTranscript 4 320 minutes (3 jours)
    Canal Teams 4 320 minutes (3 jours)
    Conversation Teams 4 320 minutes (3 jours)
    chatmessage Teams 4 320 minutes (3 jours)
    conversationMember Teams 4 320 minutes (3 jours)
    Teams onlineMeeting 4 320 minutes (3 jours)
    Équipe Teams 4 320 minutes (3 jours)
    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.

    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
    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
    onlineMeeting Moins de 10 secondes 1 minute
    présence Moins de 10 secondes 1 minute
    imprimante Less than 1 minute 5 minutes
    printTaskDefinition Less than 1 minute 5 minutes
    équipe Moins de 10 secondes 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.

    Contenu connexe