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

Les applications s’abonnant à des notifications pour les ressources Outlook peuvent voir leur abonnement supprimé et rater certaines notifications.Apps subscribing to notifications for Outlook resources may get their subscriptions removed and miss some 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 continu.Apps should implement logic to detect and recover from the loss, and resume a continuous 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 ne peut pas être remise à une application.Outlook also sends another lifecycle notification, missed, if a notification cannot be delivered to an app.

Une application s’abonnant aux notifications pour les ressources Outlook, telles que message et événement, doit écouter les signaux subscriptionRemoved et missed :An app subscribing to notifications for Outlook resources, such as message and event, should listen to the subscriptionRemoved and missed signals:

  • Lorsqu’elle reçoit une subscriptionRemoved notification, l’application doit recréer l’abonnement afin de maintenir un flux continu.Upon receiving a subscriptionRemoved notification, the app should recreate the subscription in order to maintain a continuous flow.
  • En recevant une missed notification, l’application doit resynchroniser les données de ressource à l’aide de Microsoft Graph.On receiving a missed 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 ressources, ou vous pouvez vous en enregistrer un distinct lifecycleNotificationUrl pour recevoir subscriptionRemoved et missed les notifications dans un point de terminaison distinct.To receive lifecycle notifications, you can use the existing notificationUrl endpoint that already receives resource notifications, or you can register a separate lifecycleNotificationUrl to receive subscriptionRemoved and missed notifications in a separate endpoint.

Création d’un abonnementCreating a subscription

Lorsque vous créez un abonnement, vous pouvez spécifier un point de terminaison de notification distinct à l’aide la propriétélifecycleNotificationUrl.When creating a subscription, you can 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, subscriptionRemoved et missed notifications seront remises à notificationUrl existant pour tous les abonnements existants.Otherwise, subscriptionRemoved and missed notifications will be delivered to the existing notificationUrl for all existing subscriptions.

Remarque : pour l’instant, la propriétélifecycleNotificationUrl peut uniquement être définie ou lue à l’aide de la beta version de Microsoft Graph API.Note: At the moment, the lifecycleNotificationUrl property can only be set or read using the beta version of Microsoft Graph APIs. Toutefois, les abonnements créé à l’aide de beta sont stockés dans le même environnement de production que v1.0 afin que vous puissiez implémenter le nouveau flux Outlook décrit ici en plus de votre utilisation régulière dev1.0 avec d’autres abonnements.However, subscriptions created using beta are stored in the same production environment as v1.0 so you can implement the new Outlook flow described here in addition to your regular usage of v1.0 with other subscriptions.

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 de notification comme décrit dans l’article notification générique.Note: You need to validate both notification endpoints as described in the generic notification article. 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 recevront les notifications subscriptionRemoved et missed via le notificationUrl.Existing subscriptions without lifecycleNotificationUrl property will receive the subscriptionRemoved and missed notifications via the notificationUrl.

Répondre aux notifications subscriptionRemovedResponding to subscriptionRemoved notifications

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

Vous pouvez créer un abonnement de longue durée (par exemple, 3 jours) et les notifications de données de ressources commenceront à aller vers la notificationUrl.You can create a long-lived subscription (e.g. 3 days), and resource data 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 may 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 may occur that requires the app to re-authenticate the user. Dans ce cas, le flux se présente comme suit :In such a case, the flow looks 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.

    1. 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 may occur frequently for some resources, and almost never for others.
  2. Microsoft Graph envoie une subscriptionRemoved notification à la lifecycleNotificationUrl (si spécifié), ou à notificationUrl.Microsoft Graph sends a subscriptionRemoved notification to the lifecycleNotificationUrl (if specified), or the notificationUrl.

  3. Vous pouvez répondre à cette notification en créant un nouvel abonnement pour la même ressource.You can respond to this 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 ressources commencent à arriver de nouveau.If you successfully create a new subscription, resource notifications will start flowing again. Toutefois, si vous n’y parvenez pas (par exemple, l’application n’a pas pu obtenir un jeton d’accès valable), les notifications de ressources ne seront pas envoyées.However, if you fail (for example, the app could not obtain a valid access token), resource 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 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 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 resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. Traiter chaque notification dans le lot en conséquence.Process each notification in the batch accordingly.

Actions à entreprendreActions to take

  1. Accuser réception de la notification en répondant à l’appel du post avec 202 - Accepted.Acknowledge the receipt of the notification, by responding to the POST call with 202 - Accepted.
  2. Valider l’authenticité de la notification.Validate the authenticity of the notification.
  3. Vérifiez que l’application a un jeton d’accès valide à la prochaine étape.Ensure 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 (par exemple, avec un nouveau mot de passe) .Note: If you are 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 login again (e.g. with a new password). Notez qu’obtenir un nouveau jeton peut échouer, étant donné que 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 may fail, since the conditions of access may have changed, and the caller may 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 des utilisateurs à la ressource ou l’application.Note: This action may fail, because the authorization checks performed by the system may 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 may be necessary for the app to obtain a new access token from the user to successfully reauthorize a subscription. Vous pourrez réessayer ces actions plus tard, à tout moment, par exemple lorsque les conditions d’accès auront changé.You may retry these actions later, at any time, for example when the conditions of access have change. 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 re-creates 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 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 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 peuvent ne pas avoir été remises.These signals inform you that some notifications may have not 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 manqués.The "lifecycleEvent": "missed" field designates this as a signal about missed 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 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’abonnementThe 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 resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. Traiter chaque notification dans le lot en conséquence.Process each notification in the batch accordingly.

Actions à entreprendreActions to take

  1. Accuser réception de la notification en répondant à l’appel du post avec 202 - Accepted.Acknowledge the receipt of the 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. Valider l’authenticité de la notification.Validate the authenticity of the 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 seront émis.They will be posted to the same endpoint: lifecycleNotificationUrl, but they will have a different value under lifecycleEvent and may 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 comme un événement que vous prenez en charge, à l’aide de la propriétélifecycleEvent.Explicitly identify each 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. Observez les annonces de notifications pour les nouveaux scénarios, il peut y avoir davantage de types de notifications du cycle de vie à l’avenir.Watch for announcements of notifications for new scenarions, as there may be more types of lifecycle notifications in the future.

  3. Dans votre application, ignorez des événements 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 events 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