Configuration des notifications pour les modifications des données utilisateurSet up notifications for changes in user data

L’API Microsoft Graph utilise un mécanisme de webhook pour remettre des notifications de modifications aux clients. Un client est un service web qui configure sa propre URL pour recevoir des notifications de modifications. Les applications clientes utilisent des notifications de modifications pour mettre à jour leur état en cas de modifications.The Microsoft Graph API uses a webhook mechanism to deliver change notifications to clients. A client is a web service that configures its own URL to receive change notifications. Client apps use change notifications to update their state upon changes.

Lorsque Microsoft Graph accepte la demande d’abonnement, il envoie des notifications de modifications à l’URL spécifiée dans la demande.After Microsoft Graph accepts the subscription request, it pushes change notifications to the URL specified in the subscription. L’application prend ensuite les mesures correspondant à sa logique métier.The app then takes action according to its business logic. Par exemple, elle extrait plus de données, met à jour ses mises en cache et ses affichages, etc.For example, it fetches more data, updates its cache and views, and so on.

Par défaut, les notifications de modifications ne contiennent pas de données de ressource, en dehors de id.By default, change notifications do not contain resource data, other than the id. Si l’application nécessite des données de ressource, elle peut appeler les API Microsoft Graph pour obtenir l’intégralité de la ressource.If the app requires resource data, it can make calls to Microsoft Graph APIs to get the full resource. Cet article utilise la ressource utilisateur comme exemple pour l’utilisation des notifications de modifications.This article uses the user resource as an example for working with change notifications.

Une application peut également s’abonner aux notifications de modifications qui incluent des données de ressources, pour éviter d’effectuer d’autres appels API pour accéder aux données.An app can also subscribe to change notifications that include resource data, to avoid having to make additional API calls to access the data. De telles applications doivent implémenter du code supplémentaire pour gérer les exigences de ces notifications, notamment : répondre aux notifications de cycle de vie de l’abonnement, valider l’authenticité des notifications et déchiffrer les données de la ressource.Such apps will need to implement extra code to handle the requirements of such notifications, specifically: responding to subscription lifecycle notifications, validating the authenticity of notifications, and decrypting the resource data. Pour plus d’informations sur l’utilisation de ces notifications, voir Configurer des notifications de modifications qui incluent des données de ressources.For details about how to work with these notifications, see Set up change notifications that include resource data.

Ressources prises en chargeSupported resources

À l’aide de l’API Microsoft Graph, une application peut souscrire à des modifications pour les ressources suivantes :Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

Vous pouvez créer un abonnement à un dossier Outlook spécifique, par exemple la boîte de réception : me/mailFolders('inbox')/messagesYou can create a subscription to a specific Outlook folder such as the Inbox: me/mailFolders('inbox')/messages

Ou à une ressource de niveau supérieur : /me/messages, /me/contacts, /me/events, users, groups, /communications/callRecordsOr to a top-level resource: /me/messages, /me/contacts, /me/events, users, groups, /communications/callRecords

Ou à une instance de ressource spécifique : users/{id}, groups/{id}, groups/{id}/conversations, sites/{site-id}/lists/{list-id}, /communications/presences/{id}Or to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations, sites/{site-id}/lists/{list-id}, /communications/presences/{id}

Ou à n’importe quel dossier de l’espace OneDrive personnel d’un utilisateur : /drives/{id}/root /drives/{id}/root/subfolderOr to any folder in a user's personal OneDrive: /drives/{id}/root /drives/{id}/root/subfolder

Ou, au dossier racine d’un lecteur SharePoint/OneDrive Entreprise : /drive/rootOr to the root folder of a SharePoint/OneDrive for Business drive: /drive/root

Ou à une nouvelle alerte d’API de sécurité : /security/alerts?$filter=status eq 'newAlert', /security/alerts?$filter=vendorInformation/provider eq 'ASC'Or to a new Security API alert: /security/alerts?$filter=status eq 'newAlert', /security/alerts?$filter=vendorInformation/provider eq 'ASC'

Limitations de ressources Azure ADAzure AD resource limitations

Certaines limites s'appliquent aux ressources Azure AD (utilisateurs, groupes) et peuvent générer des erreurs en cas de dépassement :Certain limits apply to Azure AD based resources (users, groups) and will generate errors when exceeded:

Remarque:Ces limites ne s’appliquent pas aux ressources des services autre que Azure AD.Note: These limits do not apply to resources from services other than Azure AD. Par exemple, une application pouvez créer plusieurs abonnements plus à message ou event ressources qui sont prises en charge par le service Exchange Online dans le cadre de Microsoft Graph.For example, an app can create many more subscriptions to message or event resources, which are supported by the Exchange Online service as part of Microsoft Graph.

  • Quotas maximaux d'abonnement :Maximum subscription quotas:

    • Par application (pour tous les locataires combinés) : 50 000 abonnements au totalPer app (for all tenants combined): 50,000 total subscriptions
    • Par locataire (toutes applications combinées) : 1000 abonnements au total pour toutes les applicationsPer tenant (for all applications combined): 1000 total subscriptions across all apps
    • Par combinaison d’application et de client : un total de 100 abonnementsPer app and tenant combination: 100 total subscriptions

Lorsqu’une limite est dépassée, les tentatives de création d’un abonnement entraîne uneréponse d’erreur - 403 Forbidden.When any limit is exceeded, attempts to create a subscription will result in an error response - 403 Forbidden. La propriétémessagevous explique quelle limite a été dépassée.The message property will explain which limit has been exceeded.

  • Les clients Azure AD B2C ne sont pas pris en charge.Azure AD B2C tenants are not supported.

  • Les notifications de modifications pour les entités utilisateur ne sont pas prises en charge pour les comptes Microsoft personnels.Change notification for user entities are not supported for personal Microsoft accounts.

  • Il existe un problème connu concernant les abonnements d’utilisateurs et de groupes.A known issue exists with user and group subscriptions.

Limitations de ressources OutlookOutlook resource limitations

Lorsque vous vous abonnez à des ressources Outlook telles que des** messages**, des événements ou des contacts, si vous choisissez d’utiliser le nom d’utilisateur principal UPN dans le chemin d’accès de la ressource, la demande d’abonnement peut échouer si le nom d’utilisateur principal contient une apostrophe.When subscribing to Outlook resources such as messages, events or contacts, if you choose to use the user principal name UPN in the resource path, the subscription request might fail if the UPN contains an apostrophe. Envisagez d’utiliser des ID d’utilisateur GUID au lieu de noms d’utilisateur UPN pour éviter de rencontrer ce problème.Consider using GUID user IDs instead of UPNs to avoid running into this problem. Par exemple, au lieu d’utiliser le chemin d’accès à une ressource :For example, instead of using resource path:

/users/sh.o'neal@contoso.com/messages

Utilisez :Use:

/users/{guid-user-id}/messages

Limitation des ressources TeamsTeams resource limitations

Chaque ressource des Teams a des quotas d'abonnement différents.Each Teams resource has different subscription quotas.

  • Pour les abonnements à callRecords : ** à callRecords **:For subscriptions to callRecords:

    • Par organisation : 100 abonnements au totalPer organization: 100 total subscriptions
  • Pour les abonnements à chatMessages (chaînes ou chats) :For subscriptions to chatMessages (channels or chats):

    • Par application et par canal ou combinaison de conversation : 1 abonnementPer app and channel or chat combination: 1 subscription
    • Par organisation : 10.000 abonnements au totalPer organization: 10,000 total subscriptions

Durée de vie de l’abonnementSubscription lifetime

Les abonnements ont une durée de vie limitée.Subscriptions have a limited lifetime. Les applications doivent renouveler leur abonnement avant la date d’expiration.Apps need to renew their subscriptions before the expiration time. Sinon, elles doivent créer un nouvel abonnement.Otherwise, they need to create a new subscription. Pour consulter la liste des délais d’expiration maximaux, reportez-vous à la section Durée maximale d’abonnement par type de ressource.For a list of maximum expiration times, see Maximum length of subscription per resource type.

Les applications peuvent également annuler leur abonnement à tout moment pour ne plus recevoir de notifications de modifications.Apps can also unsubscribe at any time to stop getting change notifications.

Gestion des abonnementsManaging subscriptions

Les clients peuvent créer, renouveler et supprimer des abonnements.Clients can create subscriptions, renew subscriptions, and delete subscriptions.

Création d’un abonnementCreating a subscription

La création d’un abonnement est la première étape pour commencer à recevoir des notifications de modifications pour une ressource.Creating a subscription is the first step to start receiving change notifications for a resource. Voici les étapes à suivre pour s’abonner :The subscription process is as follows:

  1. Le client envoie une demande d’abonnement (POST) pour une ressource spécifique.The client sends a subscription (POST) request for a specific resource.

  2. Microsoft Graph vérifie la demande.Microsoft Graph verifies the request.

    • Si la demande est valide, Microsoft Graph envoie un jeton de validation à l’URL de notification.If the request is valid, Microsoft Graph sends a validation token to the notification URL.
    • Si la demande n’est pas valide, Microsoft Graph envoie une réponse avec les détails et le code correspondants.If the request is invalid, Microsoft Graph sends an error response with code and details.
  3. Le client renvoie le jeton de validation à Microsoft Graph.The client sends the validation token back to Microsoft Graph.

  4. Microsoft Graph renvoie une réponse au client.The Microsoft Graph sends a response back to the client.

Le client doit stocker l’ID d’abonnement pour mettre en corrélation des notifications de modifications avec l’abonnement.The client must store the subscription ID to correlate change notifications with the subscription.

Exemple de demande d’abonnementSubscription request example

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

Les propriétés changeType, notificationUrl, resource et expirationDateTime sont obligatoires.The changeType, notificationUrl, resource, and expirationDateTime properties are required. Consultez la rubrique relative au type de ressource d’abonnement pour connaître les définitions et les valeurs de chaque propriété.See subscription resource type for property definitions and values.

La propriété resource spécifie la ressource qui sera analysée pour les modifications.The resource property specifies the resource that will be monitored for changes. Par exemple, vous pouvez créer un abonnement à un dossier de courrier spécifique : me/mailFolders('inbox')/messages ou au nom d’un utilisateur avec l’accord d’un administrateur : users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.For example, you can create a subscription to a specific mail folder: me/mailFolders('inbox')/messages or on behalf of a user given by an administrator consent: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

Même si clientState n’est pas obligatoire, vous devez la renseigner pour respecter notre processus recommandé de gestion des notifications de modifications.Although clientState is not required, you must include it to comply with our recommended change notification handling process. La définition de cette propriété vous permettra de confirmer que les notifications de modifications que vous recevez proviennent du service Microsoft Graph.Setting this property will allow you to confirm that change notifications you receive originate from the Microsoft Graph service. Pour cette raison, la valeur de la propriété doit rester secrète et connue uniquement de votre application et du service Microsoft Graph.For this reason, the value of the property should remain secret and known only to your application and the Microsoft Graph service.

En cas de réussite, Microsoft Graph renvoie un code 201 Created et un objet subscription dans le corps.If successful, Microsoft Graph returns a 201 Created code and a subscription object in the body.

Remarque : n’importe quel paramètre de chaîne de requête inclus dans la propriété notificationUrl est inclus dans la demande HTTP POST lorsque des notifications sont envoyées.Note: Any query string parameter included in the notificationUrl property will be included in the HTTP POST request when notifications are being delivered.

Validation du point de terminaison de notificationNotification endpoint validation

Microsoft Graph valide le point de terminaison de notification fourni dans la propriété notificationUrl de la demande d’abonnement avant de créer l’abonnement.Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. Le processus de validation se déroule de la façon suivante :The validation process occurs as follows:

  1. Microsoft Graph encode un jeton de validation et l’inclut dans une demande POST à l’URL de notification :Microsoft Graph encodes a validation token and includes it in a POST request to the notification URL:

    Content-Type: text/plain; charset=utf-8
    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    
  2. Le client doit correctement décoder les validationToken fournies au cours de l’étape précédente, et échapper HTML/JavaScript.The client must properly decode the validationToken provided in the preceding step, and escape any HTML/JavaScript.

    La mise en forme d’échappement est une bonne pratique, car les acteurs malveillants peuvent utiliser le point de terminaison de notification pour le type de script entre sites d’attaques.Escaping is a good practice because malicious actors can use the notification endpoint for cross-site scripting type of attacks.

    En général, il faut considérer la valeur du jeton de validation comme opaque, car le format du jeton peut généralement changer sans préavis.In general, treat the validation token value as opaque, as the token format can generally change without notice. Microsoft Graph n’envoie jamais de valeur contenant du code HTML ou JavaScript.Microsoft Graph never sends any value containing HTML or JavaScript code.

  3. Le client doit fournir dans un délai de 10 secondes une réponse avec les caractéristiques suivantes à l’étape 1 :The client must provide a response with the following characteristics within 10 seconds of step 1:

    • Un code d’état de HTTP 200 OK.A status code of HTTP 200 OK.
    • Type de contenu de text/plain.A content type of text/plain.
    • Corps qui inclut le jeton de validation décodé.A body that includes the decoded validation token.

    Le client doit ignorer le jeton de validation après l’avoir fourni dans la réponse.The client should discard the validation token after providing it in the response.

    Important : si le client renvoie un jeton de validation encodé, la validation échoue.Important: If the client returns an encoded validation token, the validation will fail.

Vous pouvez également utiliser la collection Microsoft Postman Graph pour confirmer que votre point de terminaison applique correctement la demande de validation.Additionally, you can use the Microsoft Graph Postman collection to confirm that your endpoint properly implements the validation request. La demande de Validation de l'abonnement dans le dossier Divers offre des tests d’unités qui valident la réponse fournie par votre point de terminaison.The Subscription Validation request in the Misc folder provides unit tests that validate the response provided by your endpoint.

résultats des tests de la réponse de validation

Renouveler un abonnementRenewing a subscription

Le client peut renouveler un abonnement avec une date d’expiration de trois jours maximum à partir de l’heure de la demande.The client can renew a subscription with a specific expiration date of up to three days from the time of request. La propriété expirationDateTime est requise.The expirationDateTime property is required.

Exemple de renouvellement d’abonnementSubscription renewal example

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

En cas de réussite, Microsoft Graph renvoie un code 200 OK et un objet subscription dans le corps.If successful, Microsoft Graph returns a 200 OK code and a subscription object in the body. L’objet d’abonnement inclut la nouvelle valeur expirationDateTime.The subscription object includes the new expirationDateTime value.

Suppression d’un abonnementDeleting a subscription

Le client peut arrêter de recevoir des notifications de modifications en supprimant l’abonnement à l’aide de son ID.The client can stop receiving change notifications by deleting the subscription using its ID.

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}

En cas de réussite, Microsoft Graph renvoie un code 204 No Content.If successful, Microsoft Graph returns a 204 No Content code.

Notifications de modificationsChange notifications

Avec un client s’abonnant aux modifications apportées à une ressource, Microsoft Graph envoie une demande de POST à l’URL de notification chaque fois que la ressource change.With a client subscribing to changes to a resource, Microsoft Graph sends a POST request to the notification URL whenever the resource changes. Il envoie des notifications uniquement pour les modifications apportées au type spécifié dans l’abonnement, par exemple created.It sends notifications only for changes of the type that's specified in the subscription, for example, created.

Remarque : si un client a plusieurs abonnements qui surveillent la même ressource et utilisent la même URL de notification, Microsoft Graph peut envoyer plusieurs notifications de modifications qui correspondent à différents abonnements, affichant chacune l’ID d’abonnement correspondant.Note: If a client has multiple subscriptions that monitor the same resource and use the same notification URL, Microsoft Graph can send multiple change notifications that correspond to different subscriptions, each showing the corresponding subscription ID. Il n’est pas garanti que toutes les notifications de modifications de la demande de POST appartiennent à un seul abonnement.There is no guarantee that all change notifications in the POST request belong to a single subscription.

Exemple de notification de modificationsChange notification example

Cette section présente un exemple de notification de création de message.This section shows an example of a notification for a message creation. Lorsque l’utilisateur reçoit un message électronique, Microsoft Graph envoie une notification de modifications, comme illustré dans l’exemple suivant.When the user receives an email, Microsoft Graph sends a change notification as shown in the following example. Notez que la notification se trouve dans une collection représentée dans le champ value.Note that the notification is in a collection represented in the value field. Pour plus d’informations sur la charge utile de notification, consultez changeNotificationCollection.See changeNotificationCollection for details of the notification payload.

Lorsque de nombreuses modifications se produisent, Microsoft Graph peut envoyer plusieurs notifications qui correspondent à différents abonnements au sein d’une même demande de POST.When many changes occur, Microsoft Graph may send multiple notifications that correspond to different subscriptions in the same POST request.

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Traitement de la notification de modificationsProcessing the change notification

Votre processus doit traiter toutes les notifications de modifications reçues.Your process should process every change notification it receives. Les tâches minimales que votre application doit effectuer pour traiter une notification de modifications sont les suivantes :The following are the minimum tasks that your app must perform to process a change notification:

  1. Envoyer un code d’état 202 - Accepted dans votre réponse à Microsoft Graph.Send a 202 - Accepted status code in your response to Microsoft Graph. Dans le cas où Microsoft Graph ne reçoit pas de code de classe 2xx, celle-ci tente de publier la notification de modifications plusieurs fois, pendant une période d'environ 4 heures, après quoi la notification de modifications est rejetée et ne lui est plus envoyée.If Microsoft Graph doesn't receive a 2xx class code, it will try to publishing the change notification a number of times, for a period of about 4 hours; after that, the change notification will be dropped and won't be delivered.

    Remarque : envoyez par courrier électronique un 202 - Accepted code d’état dès que vous recevez la notification de modifications, même avant de valider son authenticité.Note: Send a 202 - Accepted status code as soon as you receive the change notification, even before validating its authenticity. Vous accusez simplement réception de la notification de modifications et évitez les tentatives superflues.You are simply acknowledging the receipt of the change notification and preventing unnecessary retries. Le délai d'attente actuel est de 30 secondes, mais il est possible qu'il soit réduit à l'avenir pour optimiser les performances du service.The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance. Si l’URL de notification ne répond pas dans un délai de 30 secondes pour plus de 10% des demandes émises par Microsoft Graph pendant une période de 10 minutes, toutes les notifications suivantes sont retardées et retentées pendant 4 heures.If the notification URL doesn't reply within 30 seconds for more than 10% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be delayed and retried for a period of 4 hours. Si une URL de notification ne répond pas dans un délai de 30 secondes pour plus de 20% des demandes émises par Microsoft Graph pendant une période de 10 minutes, toutes les notifications suivantes supprimées.If a notification URL doesn't reply within 30 seconds for more than 20% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be dropped.

  2. Valider la propriété clientState.Validate the clientState property. Elle doit correspondre à la valeur envoyée initialement avec la demande de la création de l’abonnement.It must match the value originally submitted with the subscription creation request.

    Remarque : si ce n’est pas le cas, vous ne devez pas considérer cette notification de modifications comme étant valide.Note: If this isn't true, you should not consider this a valid change notification. Il est possible que la notification de modifications ne provienne pas de Microsoft Graph et qu’elle ait été envoyée par un acteur non autorisé.It is possible that the change notification has not originated from Microsoft Graph and may have been sent by a rogue actor. Vous devez également examiner la provenance de la notification de modifications et prendre les mesures qui s’imposent.You should also investigate where the change notification comes from and take appropriate action.

  3. Mettre à jour votre application selon votre logique métier.Update your application based on your business logic.

Répétez ces étapes pour les autres notifications de modifications dans la demande.Repeat for other change notifications in the request.

Exemples de codeCode samples

Les exemples de code suivants sont disponibles sur GitHub.The following code samples are available on GitHub.

Configuration du pare-feuFirewall configuration

Vous pouvez, si vous le souhaitez, configurer le pare-feu qui protège votre URL de notification afin d’autoriser les connexions entrantes à partir de Microsoft Graph uniquement.You can optionally configure the firewall that protects your notification URL to allow inbound connections only from Microsoft Graph. Vous pouvez ainsi réduire l’exposition supplémentaire aux notifications de modifications non valides envoyées à votre URL de notification.This allows you to reduce further exposure to invalid change notifications that are sent to your notification URL. Ces notifications de modifications non valides peuvent essayer de déclencher la logique personnalisée que vous avez implémentée.These invalid change notifications can be trying to trigger the custom logic that you implemented. Pour obtenir la liste complète des adresses IP utilisées par Microsoft Graph pour transmettre des notifications de modifications, voir autres points de terminaison pour Microsoft 365.For a complete list of IP addresses used by Microsoft Graph to deliver change notifications, see additional endpoints for Microsoft 365.

Remarque : les adresses IP répertoriées et utilisées pour fournir des notifications de modifications peuvent être mises à jour à tout moment sans préavis.Note: The listed IP addresses that are used to deliver change notifications can be updated at any time without notice.

LatenceLatency

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.The following table lists the latency to expect between an event happening in the service and the delivery of the change notification.

RessourceResource Latence moyenneAverage latency Latence maximaleMaximum latency
callRecordcallRecord Moins de 15 minutesLess than 15 minutes 60 minutes60 minutes
chatMessagechatMessage Moins de 10 secondesLess than 10 seconds 1 minute1 minute
contactcontact InconnuUnknown InconnuUnknown
driveItemdriveItem Less than 1 minuteLess than 1 minute 5 minutes5 minutes
[événement][]event InconnuUnknown InconnuUnknown
[groupe][]group Moins de 2 minutesLess than 2 minutes 15 minutes15 minutes
conversationconversation InconnuUnknown InconnuUnknown
listelist Less than 1 minuteLess than 1 minute 5 minutes5 minutes
messagemessage InconnuUnknown InconnuUnknown
[alerte][]alert Moins de 3 minutesLess than 3 minutes 5 minutes5 minutes
présence (aperçu) presence (preview) Moins de 10 secondesLess than 10 seconds 1 minute1 minute
[utilisateur][]user Moins de 2 minutesLess than 2 minutes 15 minutes15 minutes

Remarque : la latence prévue pour laressource d'alerte n'est applicable qu'après la création de l'alerte elle-même. Note: The latency provided for the alert resource is only applicable after the alert itself has been created. Elle n’inclut pas le temps nécessaire à l’exécution d’une règle pour créer une alerte à partir des données.It does not include the time it takes for a rule to create an alert from the data.

Voir aussiSee also