Réduire les abonnements et notifications de modification manquants

Pendant la durée de vie d’un abonnement, Microsoft Graph envoie des types spéciaux de notifications pour vous aider à réduire le risque d’abonnements manquants et de notifications de modification. Ces notifications sont appelées notifications de cycle de vie.

Il existe trois types d’événements de cycle de vie :

• reauthorizationRequired notifications
• Notifications de suppression d’abonnement
• notifications manquées

Si vous ignorez ces événements, cela peut interrompre le flux de notification de modification ; vous pouvez gérer les événements en implémentant une logique dans votre application pour reprendre un flux de notification de modification continue.

Cet article présente les notifications de cycle de vie dans les notifications de modification Microsoft Graph et fournit des conseils pour gérer les notifications.

Ressources prises en charge

Bien que vous puissiez fournir un lifecycleNotificationUrl lors de la création d’un abonnement sur n’importe quel type de ressource, les notifications de cycle de vie sont actuellement prises en charge uniquement pour les types de ressources suivants.

• reauthorizationRequired notifications - Toutes les ressources
• subscriptionRemoved notifications : message Outlook, événement Outlook, contact personnel Outlook, chatMessage Teams
• notifications manquées : message Outlook, événement Outlook, contact personnel Outlook

Configurer votre abonnement pour recevoir des notifications de cycle de vie

Pour recevoir des notifications de cycle de vie, vous devez fournir un point de terminaison lifecycleNotificationUrl valide lors de la création de l’abonnement.

La demande de création d’abonnement suivante définit les points de terminaison notificationUrl et lifecycleNotificationUrl .

HTTP

POST https://graph.microsoft.com/v1.0/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": "2020-03-20T11:00:00.0000000Z",
  "clientState": "<secretClientState>"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ChangeType = "created,updated",
	NotificationUrl = "https://webhook.azurewebsites.net/api/resourceNotifications",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/users/{id}/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2020-03-20T11:00:00.0000000Z"),
	ClientState = "<secretClientState>",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc subscriptions create --body '{\
  "changeType": "created,updated",\
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",\
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",\
  "resource": "/users/{id}/messages",\
  "expirationDateTime": "2020-03-20T11:00:00.0000000Z",\
  "clientState": "<secretClientState>"\
}\
'

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
changeType := "created,updated"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/resourceNotifications"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/users/{id}/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2020-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "<secretClientState>"
requestBody.SetClientState(&clientState) 

subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created,updated");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/resourceNotifications");
subscription.setLifecycleNotificationUrl("https://webhook.azurewebsites.net/api/lifecycleNotifications");
subscription.setResource("/users/{id}/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2020-03-20T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("<secretClientState>");
Subscription result = graphClient.subscriptions().post(subscription);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/api/resourceNotifications',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/users/{id}/messages',
  expirationDateTime: '2020-03-20T11:00:00.0000000Z',
  clientState: '<secretClientState>'
};

await client.api('/subscriptions')
	.post(subscription);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('created,updated');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/resourceNotifications');
$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');
$requestBody->setResource('/users/{id}/messages');
$requestBody->setExpirationDateTime(new \DateTime('2020-03-20T11:00:00.0000000Z'));
$requestBody->setClientState('<secretClientState>');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/api/resourceNotifications"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/users/{id}/messages"
	expirationDateTime = [System.DateTime]::Parse("2020-03-20T11:00:00.0000000Z")
	clientState = "<secretClientState>"
}

New-MgSubscription -BodyParameter $params

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	change_type = "created,updated",
	notification_url = "https://webhook.azurewebsites.net/api/resourceNotifications",
	lifecycle_notification_url = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	resource = "/users/{id}/messages",
	expiration_date_time = "2020-03-20T11:00:00.0000000Z",
	client_state = "<secretClientState>",
)

result = await graph_client.subscriptions.post(request_body)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Le point de terminaison lifecycleNotificationUrl peut être identique à notificationUrl.

Les abonnements existants sans propriété lifecycleNotificationUrl ne reçoivent pas les notifications de cycle de vie. Pour ajouter la propriété lifecycleNotificationUrl , vous devez supprimer ces abonnements existants et créer de nouveaux abonnements tout en spécifiant la propriété lors de la création de l’abonnement.

Lorsque vous utilisez le canal de remise des webhooks, vous devez valider les deux points de terminaison.

Structure d’une notification de cycle de vie

Une charge utile de notification de cycle de vie suit la structure de la collection changeNotificationCollection et des types de ressources changeNotification associés comme suit :

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

L’événement lifecycleEvent peut être subscriptionRemoved, missedou reauthorizationRequired, représentant les types de notification de cycle de vie.

Une notification de cycle de vie ne contient pas d’informations sur une ressource spécifique, car elle n’est pas liée à une modification de ressource, mais à la modification de l’état de l’abonnement. Comme pour les notifications de modification, les notifications de cycle de vie peuvent être regroupées et reçues en tant que collection, chacune avec une valeur lifecycleEvent éventuellement différente. Traiter chaque notification de cycle de vie dans le lot en conséquence.

Lorsque vous traitez la notification de cycle de vie et que vous reprenez le flux de notifications de modification, les notifications de modification commencent à circuler vers notificationUrl.

Réponse aux notifications reauthorizationRequired

reauthorizationRequired Les événements de cycle de vie vous alertent lorsque Microsoft Graph exige que l’application réautorise l’abonnement, par exemple dans les cas suivants :

• Lorsque le jeton d’accès est sur le point d’expirer.
• Lorsqu’un abonnement est sur le point d’expirer.
• Lorsqu’un administrateur client a révoqué les autorisations de votre application pour lire une ressource.

Avant que l’une de ces conditions ne devienne vraie, Microsoft Graph envoie une demande d’autorisation à lifecycleNotificationUrl.

L’exemple de code suivant illustre la façon dont le service de notifications de modification Microsoft Graph peut calculer l’intervalle de ces notifications.

    //The following code is for illustrative purposes only
    var TokenTimeToExpirationInMinutes=(TokenExpirationTime-CurrentTime)/4;

    if((TokenTimeToExpirationInMinutes)<=180 && TokenTimeToExpirationInMinutes>60){
        //Microsoft Graph will send reauthorizationRequired notification
        TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes/2;
    }
    elseif(TokenTimeToExpirationInMinutes<60 && TokenTimeToExpirationInMinutes>=0){
            //Microsoft Graph will send reauthorizationRequired notification every 15 mins
            TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes-15;
    } else {
      //Microsoft Graph will stop sending reauthorizationRequired notifications
    }

Les étapes suivantes représentent le flux d’une stimulation d’autorisation pour un abonnement actif :

1. Microsoft Graph requiert la ré-autorisation d’un abonnement.

   Les raisons peuvent varier d’une ressource à l’autre et peuvent changer au fil du temps. Pour maintenir l’abonnement, vous devez répondre à un événement de réautorisation, quelle que soit sa cause.

2. Microsoft Graph envoie une notification de challenge d’autorisation à la lifecycleNotificationUrl.

   Le flux de notifications de modification peut se poursuivre pendant un certain temps, ce qui vous donne plus de temps pour répondre. Cependant, la remise de la notification de modification s’interrompe, jusqu’à ce que vous procédiez à l’action requise. Toutes les notifications sur les modifications de ressources qui se produisent lorsque la remise de la notification de modification s’interrompt et le moment où l’application crée correctement l’abonnement sont perdues. Dans ce cas, l’application doit extraire séparément ces modifications, par exemple à l’aide de la requête delta.

Actions à entreprendre

1. Accusez réception de la notification de cycle de vie en répondant à l’appel POST avec 202 - Accepted le code de réponse.

2. Validez l’authenticité de la notification de cycle de vie.

3. Vérifiez que l’application a un jeton d’accès valide à la prochaine étape.

4. Appelez l’une des deux API suivantes. Si l’appel d’API réussit, le flux de notification de modification reprend.

   • Appelez l’action /reauthorize pour autoriser à nouveau l’abonnement sans étendre sa date d’expiration.

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

   • Effectuez une action de « renouvellement » régulière pour réautoriser et renouveler l’abonnement en même temps.

     PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
     Content-Type: application/json
     
     {
        "expirationDateTime": "2019-09-21T11:00:00.0000000Z"
     }
     

     Le renouvellement peut échouer si l’application n’est plus autorisée à accéder à la ressource. Il peut alors être nécessaire que l’application obtienne un nouveau jeton d’accès pour réautoriser correctement un abonnement.

     Vous pourrez réessayer ces actions plus tard, à tout moment, et réussir si les conditions d’accès ont changé.

Informations supplémentaires

• Les défis d’autorisation ne remplacent pas la nécessité de renouveler un abonnement avant son expiration. Les cycles de vie des jetons d’accès et de l’expiration de l’abonnement ne sont pas les mêmes. Votre jeton d’accès peut expirer avant votre abonnement. Il est important de se préparer à réautoriser régulièrement votre point de terminaison pour actualiser votre jeton d’accès. La réautorisation de votre point de terminaison ne renouvelle pas votre abonnement. Toutefois, le renouvellement de votre abonnement réautorise également votre point de terminaison.

• La fréquence des défis liés à l’autorisation peut être modifiée.

  Ne supposez pas la fréquence des défis d’autorisation. Ces notifications de cycle de vie vous indiquent quand prendre des mesures, ce qui vous évite d’avoir à suivre les abonnements qui nécessitent une nouvelle autorisation. Soyez prêt à gérer les défis d’autorisation d’une fois toutes les quelques minutes pour chaque abonnement à rarement pour certains de vos abonnements.

Répondre aux notifications subscriptionRemoved

subscriptionRemoved Les événements de cycle de vie vous alertent lorsque Microsoft Graph a supprimé un abonnement. Dans ce cas, si vous souhaitez continuer à recevoir des notifications de modification pour la ressource associée, vous devez recréer l’abonnement.

Même si vous avez un abonnement de longue durée, les conditions d’accès aux données de ressource peuvent changer au fil du temps. Par exemple, un événement dans le service peut se produire et demander à l’application de réauthentifier l’utilisateur. Dans ce cas, Microsoft Graph vous envoie une notification abonnementRemoved .

Le flux suivant montre le flux d’un événement subscriptionRemoved :

1. Le service détecte qu’un abonnement doit être supprimé de Microsoft Graph.

   Il n’existe aucune cadence définie pour ces événements. Il peuvent se produire fréquemment pour certaines ressources et pratiquement jamais pour d’autres.

2. Microsoft Graph envoie une subscriptionRemoved notification de modification à la lifecycleNotificationUrl (si spécifié).

   Aucune notification de cycle de vie n’est disponible à partir de la période à laquelle la subscriptionRemoved notification de cycle de vie a été envoyée lorsque l’application recrée correctement l’abonnement. L’application doit extraire ces modifications seule.

Actions à entreprendre

1. Accusez réception de la notification de cycle de vie en répondant à l’appel POST avec 202 - Accepted le code de réponse.

2. Validez l’authenticité de la notification de cycle de vie.

3. Vérifiez que l’application a un jeton d’accès valide à la prochaine étape.

4. Créez un abonnement.

   Cette action peut échouer, car les vérifications d’autorisation effectuées par le système peuvent refuser à l’application l’accès à la ressource. Il peut être nécessaire que l’application obtienne un nouveau jeton d’accès pour autoriser à nouveau un abonnement. Vous pouvez réessayer ces actions plus tard, à tout moment, par exemple lorsque les conditions d’accès auront changé.

5. Après avoir créé l’abonnement, vous pouvez synchroniser les données de ressource pour identifier les notifications de modification manquées . par exemple à l’aide de la requête delta.

Répondre aux notifications manquées

missed Les événements de cycle de vie vous avertit que certaines notifications de modification n’ont peut-être pas été remises. Par exemple, en raison de la limitation.

Actions à entreprendre

1. Accusez réception de la notification de cycle de vie en répondant à l’appel POST avec 202 - Accepted le code de réponse.
2. Validez l’authenticité de la notification de cycle de vie.
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 ; par exemple, à l’aide de la requête delta.

Contenu connexe

• Type de ressource abonnement