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 aux clients. Un client est un service web qui configure sa propre URL pour recevoir des notifications. Les applications clientes utilisent des notifications pour mettre à jour leur état en cas de modifications.The Microsoft Graph API uses a webhook mechanism to deliver notifications to clients. A client is a web service that configures its own URL to receive notifications. Client apps use notifications to update their state upon changes.

Lorsque Microsoft Graph accepte la demande d’abonnement, il envoie des notifications à l’URL spécifiée dans la demande.After Microsoft Graph accepts the subscription request, it pushes 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, etc.

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:

  • messageOutlookOutlook message
  • [événement][]OutlookOutlook event
  • Recherche des[contacts][] personnels OutlookOutlook personal contact
  • [utilisateur][]user
  • [groupe][]group
  • Groupeconversation Office 365Office 365 group conversation
  • Contenus au sein de la hiérarchie de_n’importe quel dossier_ driveItem sur OneDrive personnel d’un utilisateurContent within the hierarchy of any folder driveItem on a user's personal OneDrive
  • Contenus au sein de la hiérarchie du_dossier racine_ driveItem sur OneDrive EntrepriseContent within the hierarchy of the root folder driveItem on OneDrive for Business
  • [Alerte][]de sécuritéSecurity alert

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 ou groupsOr to a top-level resource: me/messages, me/contacts, me/events, users, or groups

Ou à une instance de ressource spécifique : users/{id}, groups/{id}, groups/{id}/conversationsOr to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations

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 ‘New’, /security/alerts?$filter=vendorInformation/provider eq ‘ASC’Or to a new Security API alert: /security/alerts?$filter=status eq ‘New’, /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 : un total de 50 000 abonnementsPer app: 50,000 total subscriptions
    • Par client : un total de 1 000 abonnements pour toutes les applicationsPer tenant: 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

Lorsque les limites sont dépassés, les tentatives de création d’un abonnement entraîne uneréponse d’erreur - 403 Forbidden.When the limits are 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 pour les entités utilisateur ne sont pas prises en charge pour les comptes Microsoft personnels.Notification for user entities are not supported for personal Microsoft accounts.

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.Apps can also unsubscribe at any time to stop getting 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 pour une ressource. Voici les étapes à suivre pour s’abonner :Creating a subscription is the first step to start receiving notifications for a resource. 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 avec l’abonnement.The client must store the subscription ID to correlate 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.Although clientState is not required, you must include it to comply with our recommended notification handling process. La définition de cette propriété vous permettra de confirmer que les notifications que vous recevez proviennent du service Microsoft Graph.Setting this property will allow you to confirm that 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.

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 envoie une demande POST à l’URL de notification :Microsoft Graph sends a POST request to the notification URL:

    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    

    Important : étant donné que le jeton validationToken est un paramètre de requête, il doit être correctement décodé par le client conformément aux pratiques de codage HTTP.Important: Since the validationToken is a query parameter it must be properly decoded by the client, as per HTTP coding practices. Si le client ne décode pas le jeton et utilise à la place la valeur codée dans l’étape suivante (réponse), la validation échoue.If the client does not decode the token, and instead uses the encoded value in the next step (response), validation will fail. Par ailleurs, le client doit considérer la valeur du jeton comme étant opaque étant donné que le format du jeton peut changer ultérieurement, sans préavis.Also, the client should treat the token value as opaque since the token format may change in the future, without notice.

  2. Le client doit fournir dans un délai de 10 secondes une réponse avec les caractéristiques suivantes :The client must provide a response with the following characteristics within 10 seconds:

    • Un code d’état 200 (OK).A 200 (OK) status code.
    • Le type de contenu doit être text/plain.The content type must be text/plain.
    • Le corps doit inclure le jeton de validation fourni par Microsoft Graph.The body must include the validation token provided by Microsoft Graph.

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.

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 en supprimant l’abonnement à l’aide de son ID.The client can stop receiving 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.

NotificationsNotifications

Le client commence à recevoir des notifications après la création de l’abonnement.The client starts receiving notifications after creating the subscription. Microsoft Graph envoie une demande POST à l’URL de notification lorsque la ressource est modifiée.Microsoft Graph sends a POST request to the notification URL when the resource changes. Les notifications sont envoyées uniquement pour les modifications du type spécifié dans l’abonnement, par exemple, created.Notification are sent only for the changes of the type specified in the subscription, for example, created.

Remarque : lorsque vous utilisez plusieurs abonnements qui surveillent le même type de ressource et utilisent la même URL de notification, une demande POST contenant plusieurs notifications avec différents ID d’abonnement peut être envoyée.Note: When using multiple subscriptions that monitor the same resource type and use the same notification URL, a POST can be sent that will contain multiple notifications with different subscription IDs. Il n’existe aucune garantie que toutes les notifications dans la demande POST appartiendront à un seul abonnement.There is no guarantee that all notifications in the POST will belong to a single subscription.

Propriétés de notificationNotification properties

L’objet « notification » possède les propriétés suivantes :The notification object has the following properties:

PropriétéProperty TypeType DescriptionDescription
subscriptionIdsubscriptionId stringstring ID de l’abonnement ayant généré la notification.The ID of the subscription that generated the notification.
subscriptionExpirationDateTimesubscriptionExpirationDateTime dateTimedateTime Délai d’expiration de l’abonnement.The expiration time for the subscription.
clientStateclientState stringstring Propriété clientState spécifiée dans la demande d’abonnement (le cas échéant).The clientState property specified in the subscription request (if any).
changeTypechangeType stringstring Type d’événement ayant généré la notification.The event type that caused the notification. Par exemple, created lors de la réception d’un e-mail, ou updated lorsqu’un message est marqué comme lu.For example, created on mail receive, or updated on marking a message read.
ressourceresource stringstring URI de la ressource relative à https://graph.microsoft.com.The URI of the resource relative to https://graph.microsoft.com.
resourceDataresourceData objetobject Le contenu de cette propriété dépend du type de ressource concerné par l’abonnement.The content of this property depends on the type of resource being subscribed to.

Par exemple, pour les ressources Outlook, resourceData contient les champs suivants :For example, for Outlook resources, resourceData contains the following fields:

PropriétéProperty TypeType DescriptionDescription
@odata.type@odata.type stringstring Type d’entité OData dans Microsoft Graph qui décrit l’objet représenté.The OData entity type in Microsoft Graph that describes the represented object.
@odata.id@odata.id stringstring Identificateur OData de l’objet.The OData identifier of the object.
@odata.etag@odata.etag stringstring Balise d’entité HTTP qui représente une version de l’objet.The HTTP entity tag that represents the version of the object.
idid stringstring Identificateur de l’objet.The identifier of the object.

Remarque : la valeur id fournie dans resourceData est valide au moment de la génération de la notification.Note: The id value provided in resourceData is valid at the time the notification was generated. À cause de certaines actions, telles que le déplacement d’un message vers un autre dossier, l’id peut ne plus être valide lors du traitement de la notification.Some actions, such as moving a message to another folder, may result in the id no longer being valid when the notification is processed.

Exemple de notificationNotification example

Lorsque l’utilisateur reçoit un e-mail, Microsoft Graph envoie une notification semblable à celle-ci :When the user receives an email, Microsoft Graph sends a notification like the following:

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@<tenant_guid>/messages/{long_id_string}",
      "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>"
      }
    }
  ]
}

Le champ value est un tableau d’objets.Note the value field is an array of objects. Lorsque de nombreuses notifications sont mises en file d’attente, Microsoft Graph peut envoyer plusieurs éléments dans une seule demande.When there are many queued notifications, Microsoft Graph may send multiple items in a single request. Des notifications provenant de différents abonnements peuvent être incluses dans la même demande de notification.Notifications from different subscriptions can be included in the same notification request.

Traitement de la notificationProcessing the notification

Chaque notification reçue par votre application doit être traitée.Each notification received by your app should be processed. Les tâches minimales que votre application doit effectuer pour traiter une notification sont les suivantes :The following are the minimum tasks that your app must perform to process a notification:

  1. 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 comme étant valide.Note: If this isn't true, you should not consider this a valid notification. Il est possible que la notification ne provienne pas de Microsoft Graph et qu’elle ait été envoyée par un acteur non autorisé.It is possible that the 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 et prendre les mesures qui s’imposent.You should also investigate where the notification comes from and take appropriate action.

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

  3. 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. Si Microsoft Graph ne reçoit pas un code de classe 2xx, il va réessayez d’envoyer la notification plusieurs fois.If Microsoft Graph doesn't receive a 2xx class code, it will retry the notification a number of times.

    Remarque : vous devez envoyer un code d’état 202 - Accepted même si la propriété clientState ne correspond pas à celle envoyée dans la demande d’abonnement.Note: You should send a 202 - Accepted status code even if the clientState property doesn't match the one submitted with the subscription request. Il s’agit d’une bonne pratique car elle empêche un acteur non autorisé potentiel de découvrir que vous ne faites peut-être pas confiance à ses notifications, et éventuellement d’utiliser ces informations pour identifier la valeur de la propriété clientState.This is a good practice as it prevents a potential rogue actor from discovering the fact that you may not trust their notifications, and perhaps using that information to guess the value of the clientState property.

Répétez ces étapes pour les autres notifications dans la demande.Repeat for other 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.

Voir aussiSee also