Réduire les abonnements et notifications de modification manquants pour les ressources Outlook (aperçu)Reduce missing subscriptions and change notifications for Outlook resources (preview)

Les applications s’abonnant à des notifications de modification pour les ressources Outlook peuvent voir leur abonnement supprimé et rater certaines notifications de modification.Apps subscribing to change notifications for Outlook resources might get their subscriptions removed and miss some change notifications. Les applications devraient implémenter une logique pour détecter et récupérer à partir de la perte et reprendre un flux de notifications de modification continu.Apps should implement logic to detect and recover from the loss, and resume a continuous change notification flow.

Certains événements dans Outlook peuvent entraîner la suppression d’un abonnement.Certain events in Outlook can cause a subscription to be removed. Il peut s’agir notamment des événements suivants :These events include:

  • Le mot de passe utilisateur a été réinitialiséUser's password has been reset
  • L’appareil de l’utilisateur n’est pas conformeUser's device is out of compliance
  • Le compte d’utilisateur a été révoquéUser's account has been revoked

Quand un tel événement se produit, Outlook envoie une notification de cycle de vie spécial subscriptionRemoved.When such an event happens, Outlook sends a special lifecycle notification, subscriptionRemoved.

Outlook envoie également une autre notification de cycle de vie, missed, si une notification de modification ne peut pas être remise à une application.Outlook also sends another lifecycle notification, missed, if a change notification cannot be delivered to an app.

Une application s’abonnant aux notifications de modification pour les ressources Outlook, telles que message et événement, doit écouter les signaux subscriptionRemoved et missed procéder de la manière suivante :An app subscribing to change notifications for Outlook resources, such as message and event, should listen to the subscriptionRemoved and missed signals and do the following:

  • Lorsqu’elle reçoit une subscriptionRemoved notification de cycle de vie, l’application doit recréer l’abonnement afin de maintenir un flux continu.Upon receiving a subscriptionRemoved lifecycle notification, the app should recreate the subscription in order to maintain a continuous flow.
  • En recevant une missed notification de cycle de vie, l’application doit resynchroniser les données de ressource à l’aide de Microsoft Graph.On receiving a missed lifecycle notification, the app should resynchronize resource data using Microsoft Graph.

Pour recevoir des notifications de cycle de vie, vous pouvez utiliser le point de terminaison existant notificationUrlqui reçoit déjà les notifications de modification, ou vous pouvez vous en enregistrer un distinct lifecycleNotificationUrl pour recevoir subscriptionRemoved et missed les notifications de cycle de vie dans un point de terminaison distinct.To receive lifecycle notifications, you can use the existing notificationUrl endpoint that already receives change notifications, or you can register a separate lifecycleNotificationUrl to receive subscriptionRemoved and missed lifecycle notifications in a separate endpoint.

Création d’un abonnementCreating a subscription

Lorsque vous créez un abonnement, vous devez spécifier un point de terminaison de notification distinct à l’aide la propriétélifecycleNotificationUrl.When creating a subscription, you must specify a separate notification endpoint using the lifecycleNotificationUrl property. Si vous spécifiez le point de terminaison, tous les types de notifications de cycle de vie actuels et futurs seront remises ici.If you specify the endpoint, all current and future types of lifecycle notifications will be delivered there. Dans le cas contraire, les notifications de cycle de vie subscriptionRemoved et missed ne seront pas remises.Otherwise, subscriptionRemoved and missed lifecycle notifications will not be delivered.

Remarque : la propriétélifecycleNotificationUrl peut uniquement être définie ou lue à l’aide de la version bêta des API Microsoft Graph.Note: The lifecycleNotificationUrl property can only be set or read using Microsoft Graph beta APIs. Toutefois, les abonnements créé à l’aide de la version bêta des API sont stockés dans le même environnement de production que ceux créés avec la version 1.0, afin que vous puissiez implémenter le nouveau flux Outlook en plus de vos abonnements créés avec les API v1.0.However, subscriptions created using beta APIs are stored in the same production environment as those created using v1.0, so you can implement the new Outlook flow in addition to your subscriptions creating using v1.0 APIs.

Les abonnements créés par le biais des API v1.0 reçoivent des notifications de cycle de vie.Subscriptions created via the v1.0 APIs will receive lifecycle notifications.

Exemple de demande d’abonnementSubscription request example

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/users/{id}/messages",
  "expirationDateTime": "2019-03-20T11:00:00.0000000Z",
  "clientState": "<secretClientState>"
}

Important : utiliser le même nom d’hôte pour les deux URL de notifications.Important: Use the same hostname for both notifications URLs.

Remarque : vous devez valider les deux points de terminaison comme décrit dans Gérer les abonnements.Note: You need to validate both endpoints as described in Managing subscriptions. Si vous choisissez d’utiliser la même URL pour les deux points de terminaison, vous recevrez et répondrez aux deux demandes de validation.If you choose to use the same URL for both endpoints you will receive and respond to two validation requests.

Remarque : vous ne pouvez pas mettre à jour les (PATCH) abonnements existants pour ajouter la propriété lifecycleNotificationUrl.Note: You cannot update (PATCH) the existing subscriptions to add the lifecycleNotificationUrl property. Vous devez supprimer ces abonnements existants et créer de nouveaux abonnements et spécifier la propriétélifecycleNotificationUrl.You should remove such existing subscriptions, and create new subscriptions and specify the lifecycleNotificationUrl property. Les abonnements existants sans propriétélifecycleNotificationUrl ne recevront pas les notifications subscriptionRemoved et missed.Existing subscriptions without lifecycleNotificationUrl property will not receive the subscriptionRemoved and missed.

Répondre aux notifications subscriptionRemovedResponding to subscriptionRemoved notifications

La subscriptionRemoved notification de notification vous informe qu’un abonnement a été supprimé et doit être recréé, si vous voulez continuer à recevoir des notifications.The subscriptionRemoved lifecycle notification informs you that a subscription has been removed and should be recreated, if you want to continue receiving change notifications.

Vous pouvez créer un abonnement de longue durée (3 jours) et les notifications de modification commenceront à aller vers la notificationUrl.You can create a long-lived subscription (3 days), and change notifications will start flowing to the notificationUrl. Toutefois, les conditions d’accès aux données de ressources peuvent changer au fil du temps.However, the conditions of access to the resource data might change over time. Par exemple, un événement dans le service Outlook peut se produire amenant l’application à authentifier de nouveau l’utilisateur.For example, an event in the Outlook service might occur that requires the app to re-authenticate the user. Dans ce cas, le flux est le suivant :In such a case, the flow is as follows:

  1. Outlook détecte qu’un abonnement doit être supprimé de Microsoft Graph.Outlook detects that a subscription needs to be removed from Microsoft Graph.

    Il n’existe aucune cadence fixe pour ces événements.There is no set cadence for these events. Il peuvent se produire fréquemment pour certaines ressources et pratiquement jamais pour d’autres.They might occur frequently for some resources, and almost never for others.

  2. Microsoft Graph envoie une subscriptionRemoved notification de modification à la lifecycleNotificationUrl (si spécifié).Microsoft Graph sends a subscriptionRemoved lifecycle notification to the lifecycleNotificationUrl (if specified).

  3. Vous pouvez répondre à cette notification de cycle de vie en créant un nouvel abonnement pour la même ressource.You can respond to this lifecycle notification by creating a new subscription for the same resource. Pour ce faire, vous devez présenter un jeton d’accès valide ; dans certains cas, cela signifie que l’application a besoin d’authentifier à nouveau l’utilisateur pour obtenir un nouveau jeton d’accès valide.To do this, you need to present a valid access token; in some cases this means the app needs to re-authenticate the user to obtain a new valid access token.

  4. Si vous créez correctement un nouvel abonnement, les notifications de modification commencent à arriver de nouveau.If you successfully create a new subscription, change notifications will start flowing again. Toutefois, si vous n’y parvenez pas (par exemple, si l’application ne peut pas obtenir un jeton d’accès valable), les notifications de modification ne seront pas envoyées.However, if you fail (for example, the app can't obtain a valid access token), change notifications will not be sent.

  5. Après avoir créé le nouvel abonnement, vous pouvez synchroniser les données de ressources afin d’identifier les modifications manquantes.After creating the new subscription, you can sync the resource data to identify any missing changes.

Exemple de notification subscriptionRemovedsubscriptionRemoved notification example

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2019-03-20T11:00:00.0000000Z",
      "tenantId": "<tenant_guid>",
      "clientState":"<secretClientState>",
      "lifecycleEvent": "subscriptionRemoved"
    }
  ]
}

Quelques éléments à noter sur ce type de notification :A few things to note about this type of notification:

  • Le "lifecycleEvent": "subscriptionRemoved" champ désigne cette notification comme liée à la suppression de l’abonnement.The "lifecycleEvent": "subscriptionRemoved" field designates this notification as related to subscription removal. Les autres types de notifications du cycle de vie sont également possibles et de nouvelles seront introduites à l’avenir.Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • La notification de cycle de vie ne contient pas d’informations sur une ressource spécifique, car elle n’est pas liée à un changement de ressources, mais à la modification d’état de l’abonnement.The lifecycle notification does not contain any information about a specific resource, because it is not related to a resource change, but to the subscription state change.
  • Tout comme les notifications de modification, les notifications de cycle de vie peuvent être regroupées (dans la matrice valeur), chacune avec une valeur différente lifecycleEvent.Similar to change notifications, lifecycle notifications can be batched together (in the value array), each with a possibly different lifecycleEvent value. Traiter chaque notification de cycle de vie dans le lot en conséquence.Process each lifecycle notification in the batch accordingly.

Remarque : pour une description complète des données envoyées lorsque les notifications de modification sont transmises, voir changeNotificationCollection.Note: for a full description of the data sent when change notifications are delivered, see changeNotificationCollection.

Actions à entreprendreActions to take

  1. Accuser réception de la notification de cycle de vie en répondant à l’appel du post avec 202 - Accepted.Acknowledge the receipt of the lifecycle notification, by responding to the POST call with 202 - Accepted.
  2. Validez l’authenticité de la notification de cycle de vie.Validate the authenticity of the lifecycle notification.
  3. Vérifiez que l’application a un jeton d’accès valide à la prochaine étape.Ensure that the app has a valid access token to take the next step.

Remarque : si vous utilisez une des bibliothèques d’authentification, elles gèrent cela pour vous en réutilisant un jeton de mise en cache valide ou en obtenant un nouveau jeton, y compris en demandant à l’utilisateur de se reconnecter (avec un nouveau mot de passe) .Note: If you're using one of the authentication libraries, they will handle this for you by either reusing a valid cached token, or obtaining a new token, including asking the user to sign in again (with a new password). Notez qu’obtenir un nouveau jeton peut échouer, car les conditions d’accès peuvent avoir changé et l’appelant peut ne plus être autorisé à accéder aux données de ressource.Note that obtaining a new token might fail, because the conditions of access might have changed, and the caller might no longer be allowed access to the resource data.

  1. Créer un nouvel abonnement en utilisant le processus standard décrit ici.Create a new subscription using the standard process described here.

Remarque : cette action peut échouer, car les vérifications d’autorisation effectuées par le système peuvent refuser l’accès de l’application ou des utilisateurs à la ressource.Note: This action might fail, because the authorization checks performed by the system might deny the app or the user access to the resource. Il peut être nécessaire pour l’application d’obtenir un nouveau jeton d’accès de l’utilisateur pour autoriser un abonnement à l’application.It might be necessary for the app to obtain a new access token from the user to successfully reauthorize a subscription. Vous pouvez réessayer ces actions plus tard, à tout moment, par exemple lorsque les conditions d’accès auront changé.You can retry these actions later, at any time; for example, when the conditions of access have changed. Les modifications de ressource dans la période de lorsque la notification de cycle de vie a été envoyée, à lorsque l’application crée un nouvel abonnement correctement, seront perdues.Any resource changes in the time period from when the lifecycle notification was sent, to when the app recreates the subscription successfully, will be lost. L’application doit récupérer ces modifications elle-même.The app will need to fetch those changes on its own.

  1. Après avoir créé le nouvel abonnement, synchronisez les données de ressources manquantes à partir de la dernière fois où vous avez reçu une notification de modification pour cette ressource ; par exemple : GET https://graph.microsoft.com/v1.0/users/{id}/messages?$filter=createdDateTime+ge+{LastTimeNotificationWasReceived}After creating the new subscription, sync any missing resource data from the last known time you received a change notification for this resource; for example: GET https://graph.microsoft.com/v1.0/users/{id}/messages?$filter=createdDateTime+ge+{LastTimeNotificationWasReceived}

Répondre aux notifications manquéesResponding to missed notifications

Ces signaux vous informent que certaines notifications de modification peuvent ne pas avoir été remises.These signals inform you that some change notifications might not have been delivered. Vous devez décider si vous ignorez ou gérez ces signaux.You should decide if you ignore or handle these signals.

Exemple de notificationNotification example

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2019-03-20T11:00:00.0000000Z",
      "tenantId": "<tenant_guid>",
      "clientState":"<secretClientState>",
      "lifecycleEvent": "missed"
    }
  ]
}

Quelques éléments à noter sur ce type de notification :A few things to note about this type of notification:

  • Le "lifecycleEvent": "missed" champ désigne ceci comme un signal à propos des notifications de modification manqués.The "lifecycleEvent": "missed" field designates this as a signal about missed change notifications. Les autres types de notifications du cycle de vie sont également possibles et de nouvelles seront introduites à l’avenir.Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • La notification de cycle de vie ne contient pas d’informations sur une ressource spécifique, car elle n’est pas liée à un changement de ressources, mais à la modification d’état de l’abonnement.The lifecycle notification does not contain any information about a specific resource, because it is not related to a resource change, but to the subscription state change.
  • Tout comme les notifications de ressources, les notifications de cycle de vie peuvent être regroupées (dans la matrice valeur), chacune avec une différente valeur lifecycleEvent.Similar to change notifications, lifecycle notifications might be batched together (in the value array), each with a possibly different lifecycleEvent value. Traiter chaque notification de cycle de vie dans le lot en conséquence.Process each lifecycle notification in the batch accordingly.

Remarque : pour une description complète des données envoyées lorsque les notifications de modification sont transmises, voir changeNotificationCollection.Note: for a full description of the data sent when change notifications are delivered, see changeNotificationCollection.

Actions à entreprendreActions to take

  1. Accuser réception de la notification de cycle de vie en répondant à l’appel du post avec 202 - Accepted.Acknowledge the receipt of the lifecycle notification, by responding to the POST call with 202 - Accepted.
    • Si vous ignorez ces signaux, ne faites rien d’autre.If you ignore these signals, do nothing else. Sinon :Otherwise:
  2. Validez l’authenticité de la notification de cycle de vie.Validate the authenticity of the lifecycle notification.
  3. Effectuez une resynchronisation complète des données de la ressource pour identifier les modifications qui n’ont pas été remises en tant que notifications.Perform a full data resync of the resource to identify the changes that were not delivered as notifications.

Vérifiez le futur code de gestion des notifications de cycle de vieFuture-proof the code handling lifecycle notifications

À l’avenir, Microsoft Graph ajoute davantage de types de notifications du cycle de vie d’abonnement.In the future, Microsoft Graph will add more types of subscription lifecycle notifications. Ils seront publiés dans le même point de terminaison : lifecycleNotificationUrl, mais ils auront une valeur différente sous lifecycleEvent et pourront contenir un schéma légèrement différent et des propriétés spécifiques au scénario dont ils proviendront.They will be posted to the same endpoint: lifecycleNotificationUrl, but they will have a different value under lifecycleEvent and might contain a slightly different schema and properties, specific to the scenario for which they will be issued.

Vous devez implémenter votre code de façon durable afin qu’il n’échoue pas lorsque Microsoft Graph présente de nouveaux types de notifications de cycle de vie.You should implement your code in a future-proof way so it does not break when Microsoft Graph introduces new types of lifecycle notifications. Nous vous recommandons les options suivantes :We recommend the following approach:

  1. Identifier explicitement chaque notification de modification comme un événement que vous prenez en charge, à l’aide de la propriétélifecycleEvent.Explicitly identify each lifecycle notification as an event that you support, using the lifecycleEvent property. Par exemple, recherchez la propriété"lifecycleEvent": "subscriptionRemoved" pour identifier un événement spécifique et le gérer.For example, look for the "lifecycleEvent": "subscriptionRemoved" property to identify a specific event, and handle it.

  2. Regardez les annonces relatives aux notifications de cycle de vie pour les nouveaux scenarios.Watch for announcements of lifecycle notifications for new scenarions. Il pourra y avoir plus de types de notifications de cycle de vie à l’avenir.There might be more types of lifecycle notifications in the future.

  3. Dans votre application, ignorez des notification de cycle de vie que l’application ne reconnaît pas et enregistrez-les pour une meilleure prise en charge.In your app, ignore any lifecycle notification that the app does not recognize, and log them to gain awareness.

  4. Recherchez la documentation connexe pour les nouvelles notifications de cycle de vie à votre convenance et implémentez leur prise en charge de manière appropriée.At your discretion, look up the related documentation for new lifecycle notifications and implement support for them as appropriate.

Voir aussiSee also