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

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.

Lorsque Microsoft Graph accepte la demande d’abonnement, il envoie des notifications de modifications à l’URL spécifiée dans la demande. L’application prend ensuite les mesures correspondant à sa logique métier. Par exemple, elle extrait plus de données, met à jour son cache et des affichages et ainsi de suite.

Par défaut, les notifications de modifications ne contiennent pas de données de ressource, en dehors de 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. Cet article utilise la ressource utilisateur comme exemple pour l’utilisation des notifications de modifications.

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. 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. Pour plus d’informations sur l’utilisation de ces notifications, voir Configurer des notifications de modifications qui incluent des données de ressources.

Ressources prises en charge

À l’aide de l’API Microsoft Graph, une application peut souscrire à des modifications pour les ressources suivantes :

Exemples de scénarios

Vous pouvez créer un abonnement pour les scénarios suivants :

Scénario Requête
Vers un dossier Outlook spécifique tel que la boîte de réception me/mailFolders('inbox')/messages
Vers une ressource de niveau supérieur /me/messages
/me/contacts
/me/events
/users
/groups
/communications/callRecords
Vers une instance de ressource spécifique /users/{id}
/groups/{id}
/groups/{id}/conversations
/sites/{site-id}/lists/{list-id}
/communications/presences/{id}
/communications/onlinemeeting/{meeting-id}
Vers n’importe quel dossier dans le OneDrive personnel d’un utilisateur /drives/{id}/root
/drives/{id}/root/subfolder
Vers le dossier racine d’un lecteur SharePoint/OneDrive Entreprise /drive/root
Ou à une nouvelle alerte de l’API de sécurité /security/alerts?$filter=status eq 'newAlert'
/security/alerts?$filter=vendorInformation/provider eq 'ASC'
Ou aux tâches dans la liste To Do d’un utilisateur /me/todo/lists/{todoTaskListId}/tasks

Limitations de ressources Azure AD

Certaines limites s'appliquent aux ressources Azure AD (utilisateurs, groupes) et peuvent générer des erreurs en cas de dépassement :

Remarque:Ces limites ne s’appliquent pas aux ressources des services autre que 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.

  • 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 client : un total de 100 abonnements

Lorsqu’une limite est dépassée, les tentatives de création d’un abonnement entraîne uneréponse d’erreur - 403 Forbidden. La propriétémessagevous explique quelle limite a été dépassée.

  • Les clients Azure AD B2C ne sont pas pris en charge.

  • Les notifications de modifications pour les entités utilisateur ne sont pas prises en charge pour les comptes Microsoft personnels.

  • Il existe un problème connu concernant les abonnements d’utilisateurs et de groupes.

Limitations de ressources Outlook

Lors de l’abonnement à des ressources Outlook telles que messages, événements ou contacts, si vous choisissez d’utiliser le userPrincipalName (UPN) dans le chemin d’accès à la ressource, la demande d’abonnement peut échouer si l’UPN contient une apostrophe. Envisagez d’utiliser des ID d’utilisateur au lieu de l’UPN pour éviter de faire face à ce problème. Par exemple, au lieu d’utiliser le chemin d’accès à une ressource :

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

Utilisez :

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

Nous autorisons un maximum de 1000 abonnements actifs par boîte aux lettres pour toutes les applications.

Limitation des ressources Teams

Chaque ressource des Teams a des quotas d'abonnement différents.

  • Pour les abonnements à callRecords : à callRecords:

    • Par organisation : 100 abonnements au total
  • Pour les abonnements à chatMessages (chaînes ou chats) :

    • Par application et par canal ou combinaison de conversation : 1 abonnement
    • Par organisation : 10.000 abonnements au total

Durée de vie de l’abonnement

Les abonnements ont une durée de vie limitée. Les applications doivent renouveler leur abonnement avant la date d’expiration. Sinon, elles doivent créer un nouvel abonnement. Pour consulter la liste des délais d’expiration maximaux, reportez-vous à la section Durée maximale d’abonnement par type de ressource.

Les applications peuvent également annuler leur abonnement à tout moment pour ne plus recevoir de notifications de modifications.

Gestion des abonnements

Les clients peuvent créer, renouveler et supprimer des abonnements.

Création d’un abonnement

La création d’un abonnement est la première étape pour commencer à recevoir des notifications de modifications pour une ressource. Voici les étapes à suivre pour s’abonner :

  1. Le client envoie une demande d’abonnement (POST) pour une ressource spécifique.

  2. Microsoft Graph vérifie la demande.

    • Si la demande est valide, Microsoft Graph envoie un jeton de validation à l’URL de notification.
    • Si la demande n’est pas valide, Microsoft Graph envoie une réponse avec les détails et le code correspondants.
  3. Le client renvoie le jeton de validation à Microsoft Graph.

  4. Microsoft Graph renvoie une réponse au client.

Le client doit stocker l’ID d’abonnement pour mettre en corrélation des notifications de modifications avec l’abonnement.

Exemple de demande d’abonnement

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. Consultez la rubrique relative au type de ressource d’abonnement pour connaître les définitions et les valeurs de chaque propriété.

La propriété resource spécifie la ressource qui sera analysée pour les modifications. 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.

Même si clientState n’est pas obligatoire, vous devez la renseigner pour respecter notre processus recommandé de gestion des notifications de modifications. La définition de cette propriété vous permettra de confirmer que les notifications de modifications que vous recevez proviennent du service Microsoft Graph. Pour cette raison, la valeur de la propriété doit rester secrète et connue uniquement de votre application et du service Microsoft Graph.

En cas de réussite, Microsoft Graph renvoie un code 201 Created et un objet subscription dans le corps.

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.

Validation du point de terminaison de notification

Microsoft Graph valide le point de terminaison de notification fourni dans la notificationUrl propriété de la demande d'abonnement avant de créer l'abonnement. Le processus de validation se déroule comme suit :

  1. Microsoft Graph encode un jeton de validation et l’inclut dans une demande POST à l’URL de notification :

    Content-Type: text/plain; charset=utf-8
    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    
  2. Le client doit correctement décoder URL le validationToken paramètre de requête fourni à l’étape précédente, et échapper 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.

    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. Microsoft Graph n’envoie jamais de valeur contenant du code HTML ou JavaScript.

  3. Le client doit fournir dans un délai de 10 secondes une réponse avec les caractéristiques suivantes à l’étape 1 :

    • Un code d’état de HTTP 200 OK.
    • Type de contenu de text/plain.
    • Corps qui inclut le jeton de validation URL décodé. Il suffit de renvoyer la chaîne envoyée dans le paramètre de requête validationToken .

    Le client doit ignorer le jeton de validation après l’avoir fourni dans la réponse.

    Important : si le client renvoie un jeton de validation encodé, la validation échoue.

Vous pouvez également utiliser la collection Microsoft Postman Graph pour confirmer que votre point de terminaison applique correctement la demande de validation. 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.

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

Renouveler un abonnement

Le client peut renouveler un abonnement avec une date d'expiration spécifique jusqu'à trois jours à partir du moment de la demande. La expirationDateTime propriété est obligatoire.

Exemple de renouvellement d’abonnement

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 retourne un code 200 OK et un objet d’abonnement dans le corps. L’objet d’abonnement inclut la nouvelle valeur expirationDateTime.

Suppression d’un abonnement

Le client peut arrêter de recevoir des notifications de modifications en supprimant l’abonnement à l’aide de son ID.

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

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

Notifications de modifications

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. Il envoie des notifications uniquement pour les modifications apportées au type spécifié dans l’abonnement, par exemple created.

Remarque : si un client dispose de plusieurs abonnements qui surveillent la même ressource et utilisent la même URL de notification, Microsoft Graph peut envoyer plusieurs notifications de changement correspondant à différents abonnements, chacun affichant l'ID d'abonnement correspondant. Il n'y a aucune garantie que toutes les notifications de changement dans la POST demande appartiennent à un seul abonnement.

Exemple de notification de modifications

Cette section présente un exemple de notification de création de message. Lorsque l’utilisateur reçoit un message électronique, Microsoft Graph envoie une notification de modifications, comme illustré dans l’exemple suivant. Notez que la notification se trouve dans une collection représentée dans le champ value. Pour plus d’informations sur la charge utile de notification, consultez changeNotificationCollection.

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.

{
  "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 modifications

Votre processus doit traiter toutes les notifications de modifications reçues. Les tâches minimales que votre application doit effectuer pour traiter une notification de modifications sont les suivantes :

  1. Votre processus doit traiter chaque notification de modification qu’il reçoit et envoyer un code de classe 2xx. Dans le cas où Microsoft Graph ne reçoit pas de code de classe 2xx dans les 3 secondes, 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 sera pas remise. Si votre processus ne répond pas systématiquement dans les 3 secondes, votre notification peut être soumise à une limitation.

    Si votre traitement est censé prendre plus de 3 secondes, vous devez faire persister la notification, renvoyer un code d’état 202 - Accepted dans votre réponse à Microsoft Graph, puis traiter les notifications. Si la notification n’est pas persistante, renvoyez un code de classe 5xx pour indiquer une erreur afin que la notification soit retentée.

    Si votre traitement est censé prendre moins de 3 secondes, vous devez traiter les notifications et renvoyer un code d’état 200 - OK dans votre réponse à Microsoft Graph. Si la notification n’est pas traitée correctement, renvoyez un code de classe 5xx pour indiquer une erreur afin que la notification soit retentée.

  2. Validez la clientState propriété. Elle doit correspondre à la valeur initialement soumise avec la demande de création d'abonnement.

    Remarque : si ce n’est pas le cas, vous ne devez pas considérer cette notification de modifications comme étant valide. 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é. Vous devez également examiner la provenance de la notification de modifications et prendre les mesures qui s’imposent.

  3. Mettre à jour votre application selon votre logique métier.

Répétez ces étapes pour les autres notifications de modifications dans la demande.

Limitation

Envoyez un code d’état 202 - Accepted dès que vous recevez la notification de modification, avant même de valider son authenticité. Vous accusez simplement réception de la notification de modifications et évitez les tentatives superflues. Pour la plupart des abonnements, les notifications ne sont soumises à aucun délai supplémentaire pendant la publication et toutes les notifications sont livrées dans le cadre du SLA, sauf si le service rencontre un incident. Toutefois, si une URL de notification d’abonnement est lente ou ne répond pas, les notifications peuvent être limitées pour l’hôte associé à l’abonnement. Le processus suivant permet de déterminer quand limiter et comment gérer les points de terminaison limités.

Les notifications sont publiées à l’aide d’un client HTTP avec un délai de 3 secondes. À la fin de la publication d’une notification, quel que soit le résultat, le temps total consacré à la publication, y compris la latence du réseau, est suivi pour l’hôte associé à l’URL de notification. Si la durée de publication est supérieure à 2900 ms, la réponse est considérée comme lente. Les réponses sont cumulées pour l’hôte et le pourcentage de réponses lentes est calculé après réception de 100 notifications. Lorsque le pourcentage de réponses lentes atteint 10 %, l’hôte associé à l’URL de notification est marqué comme point de terminaison lent. Étant donné que les points de terminaison lents sont associés à l’hôte dans l’URL de notification, toutes les notifications pour tous les abonnements associés à l’hôte sont considérées pour évaluation et soumises à une limitation.

L’évaluation se poursuit en temps réel. Si le temps de publication d’un hôte passe en dessous de 2900 ms, cette réponse non lente est incluse dans le nombre total de réponses, le pourcentage de réponses lentes est re calculé et le point de terminaison est réévalué. En outre, le nombre de réponses est vidé toutes les 10 minutes et l’évaluation recommence, en attendant 100 notifications avant d’évaluer un point de terminaison. Par conséquent, une pointe temporaire de la latence du réseau ou du retard de publication est récupérée après que le retard est atténué. Une latence de réseau plus persistante ou un retard de publication supérieur à 2900 ms sera continuellement réévalué toutes les 10 minutes.

Lorsqu’un point de terminaison est limitée, les notifications sont soumises aux délais supplémentaires suivants :

  • Les notifications sont automatiquement déchargées vers un ensemble de workers dédiés aux notifications d’échec et de limitation et un délai supplémentaire de 10 minutes est encouru.
  • Les notifications sont abandonnées si le pourcentage de ralentissement du point de terminaison limitée est >= 15 %.
  • Les notifications qui n’ont pas réussi en raison d’un appel HTTP infructueux sont de nouveau retentées dans 10 minutes.

Exemples de code

Les exemples de code suivants sont disponibles sur GitHub.

Configuration du pare-feu

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. Vous pouvez ainsi réduire l’exposition supplémentaire aux notifications de modifications non valides envoyées à votre URL de notification. Ces notifications de modifications non valides peuvent essayer de déclencher la logique personnalisée que vous avez implémentée. 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.

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.

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][] Moins de 3 minutes 5 minutes
callRecord Moins de 15 minutes 60 minutes
canal 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
liste Less than 1 minute 5 minutes
message Inconnu Inconnu
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 Moins de 2 minutes 15 minutes

Remarque : la latence prévue pour la ressource d'alerte n'est applicable qu'après la création de l'alerte elle-même. Elle n’inclut pas le temps nécessaire à l’exécution d’une règle pour créer une alerte à partir des données.

Voir aussi