Reduzieren fehlender Abonnements und Änderungsbenachrichtigungen

Während der Lebensdauer eines Abonnements sendet Microsoft Graph spezielle Arten von Benachrichtigungen, um das Risiko fehlender Abonnements und Änderungsbenachrichtigungen zu minimieren. Diese Benachrichtigungen werden als Lebenszyklusbenachrichtigungen bezeichnet.

Es gibt drei Arten von Lebenszyklusereignissen:

• reauthorizationRequired notifications
• Benachrichtigungen zum Entfernen des Abonnements
• Verpasste Benachrichtigungen

Wenn Sie diese Ereignisse ignorieren, kann dies den Änderungsbenachrichtigungsfluss unterbrechen. Sie können die Ereignisse behandeln, indem Sie Logik in Ihrer App implementieren, um einen kontinuierlichen Änderungsbenachrichtigungsfluss fortzusetzen.

In diesem Artikel werden Lebenszyklusbenachrichtigungen in Microsoft Graph-Änderungsbenachrichtigungen eingeführt und Anleitungen für die Behandlung der Benachrichtigungen bereitgestellt.

Unterstützte Ressourcen

Während Sie beim Erstellen eines Abonnements für einen beliebigen Ressourcentyp eine lifecycleNotificationUrl bereitstellen können, werden Lebenszyklusbenachrichtigungen derzeit nur für die folgenden Ressourcentypen unterstützt.

• reauthorizationRequired notifications – All resources
• abonnementRemoved-Benachrichtigungen – Outlook-Nachricht, Outlook-Ereignis, persönlicher Outlook-Kontakt, Teams chatMessage
• Verpasste Benachrichtigungen – Outlook-Nachricht, Outlook-Ereignis, persönlicher Outlook-Kontakt

Konfigurieren Ihres Abonnements für den Empfang von Lebenszyklusbenachrichtigungen

Um Lebenszyklusbenachrichtigungen zu erhalten, müssen Sie beim Erstellen des Abonnements einen gültigen lifecycleNotificationUrl-Endpunkt angeben.

Die folgende Abonnementerstellungsanforderung definiert sowohl den notificationUrl - als auch den lifecycleNotificationUrl-Endpunkt .

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>"
}

// 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://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

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>"\
}\
'

// Code snippets are only available for the latest major version. Current major version is $v1.*

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

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) 

// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

// 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);

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);

<?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();

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

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription
# To initialize your graph_client, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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)

Der lifecycleNotificationUrl-Endpunkt kann mit notificationUrl identisch sein.

Vorhandene Abonnements ohne lifecycleNotificationUrl-Eigenschaft erhalten keine Lebenszyklusbenachrichtigungen. Um die lifecycleNotificationUrl-Eigenschaft hinzuzufügen, sollten Sie solche vorhandenen Abonnements entfernen und neue Abonnements erstellen, während Sie die Eigenschaft während der Abonnementerstellung angeben.

Wenn Sie den Webhooks-Übermittlungskanal verwenden, müssen Sie beide Endpunkte überprüfen.

Struktur einer Lebenszyklusbenachrichtigung

Eine Lebenszyklusbenachrichtigungsnutzlast folgt der Struktur der changeNotificationCollection und der zugehörigen changeNotification-Ressourcentypen wie folgt:

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

Das lifecycleEvent kann , missedoder reauthorizationRequiredseinsubscriptionRemoved, das die Lebenszyklusbenachrichtigungstypen darstellt.

Eine Lebenszyklusbenachrichtigung enthält keine Informationen zu einer bestimmten Ressource, da sie sich nicht auf eine Ressourcenänderung, sondern auf die Änderung des Abonnementstatus bezieht. Ähnlich wie Änderungsbenachrichtigungen können Lebenszyklusbenachrichtigungen als Batch zusammengefasst und als Sammlung empfangen werden, die jeweils einen möglicherweise anderen lifecycleEvent-Wert aufweisen. Verarbeiten Sie jede Lebenszyklusbenachrichtigung im Batch entsprechend.

Wenn Sie die Lebenszyklusbenachrichtigung verarbeiten und den Fluss der Änderungsbenachrichtigungen fortsetzen, werden die Änderungsbenachrichtigungen an notificationUrl gesendet.

Antworten auf reauthorizationRequired-Benachrichtigungen

reauthorizationRequired Lifecycle-Ereignisse benachrichtigen Sie, wenn Microsoft Graph erfordert, dass die App das Abonnement erneut authentifizieren muss, z. B. in den folgenden Fällen:

• Wenn das Zugriffstoken bald abläuft.
• Wenn ein Abonnement bald abläuft.
• Wenn ein Mandantenadministrator die Berechtigungen Ihrer App zum Lesen einer Ressource widerrufen hat.

Bevor eine dieser Bedingungen zutrifft, sendet Microsoft Graph eine Autorisierungsanforderung an lifecycleNotificationUrl.

Das folgende Codebeispiel veranschaulicht, wie der Microsoft Graph-Änderungsbenachrichtigungsdienst das Intervall dieser Benachrichtigungen berechnen kann.

    //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
    }

Die folgenden Schritte stellen den Ablauf einer Autorisierungsaufforderung für ein aktives Abonnement dar:

1. Für Microsoft Graph muss ein Abonnement erneut autorisiert werden.

   Die Gründe können von Ressource zu Ressource variieren und sich im Laufe der Zeit ändern. Um das Abonnement zu verwalten, müssen Sie auf ein erneutes Autorisierungsereignis reagieren, unabhängig davon, was es verursacht hat.

2. Microsoft Graph sendet eine Benachrichtigung der Autorisierungsaufforderung an die lifecycleNotificationUrl.

   Der Fluss von Änderungsbenachrichtigungen kann für eine Weile fortgesetzt werden, sodass Sie mehr Zeit haben, zu reagieren. Die Zustellung der Änderungsbenachrichtigungen wird möglicherweise angehalten, bis Sie die erforderliche Aktion ausführen. Alle Benachrichtigungen über Ressourcenänderungen, die auftreten, wenn die Übermittlung der Änderungsbenachrichtigung angehalten wird und der Zeitpunkt, zu dem die App das Abonnement erfolgreich erneut erstellt, gehen verloren. In solchen Fällen sollte die App diese Änderungen separat abrufen, z. B. mithilfe der Delta-Abfrage.

Erforderliche Maßnahmen

1. Bestätigen Sie den Empfang der Lebenszyklusbenachrichtigung, indem Sie auf den POST-Aufruf mit 202 - Accepted dem Antwortcode antworten.

2. Überprüfen Sie die Echtheit der Lebenszyklusbenachrichtigung.

3. Stellen Sie sicher, dass die App über ein gültiges Zugriffstoken verfügt, um den nächsten Schritt auszuführen.

4. Rufen Sie eine der beiden folgenden APIs auf. Wenn der API-Aufruf erfolgreich ist, wird der Änderungsbenachrichtigungsfluss fortgesetzt.

   • Rufen Sie die /reauthorize Aktion auf, um das Abonnement erneut zu authentifizieren, ohne das Ablaufdatum zu verlängern.

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

   • Führen Sie eine reguläre "Verlängerungsaktion" aus, um das Abonnement gleichzeitig erneut zu authentifizieren und zu verlängern.

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

     Die Verlängerung kann fehlschlagen, wenn die App nicht mehr für den Zugriff auf die Ressource autorisiert ist. Es kann dann erforderlich sein, dass die App ein neues Zugriffstoken abruft, um ein Abonnement erfolgreich erneut zu authentifizieren.

     Sie können diese Aktionen später jederzeit wiederholen und sie kann erfolgreich sein, wenn sich die Zugriffsbedingungen ändern.

Weitere Informationen

• Autorisierungsanforderungen ersetzen nicht die Notwendigkeit, ein Abonnement zu verlängern, bevor es abläuft. Die Lebenszyklen von Zugriffstoken und Abonnementablauf sind nicht identisch. Ihr Zugriffstoken läuft möglicherweise vor Ihrem Abonnement ab. Es ist wichtig, darauf vorbereitet zu sein, Ihren Endpunkt regelmäßig erneut zu autorisieren, um Ihr Zugriffstoken zu aktualisieren. Durch die erneute Autorisierung Ihres Endpunkts wird Ihr Abonnement nicht verlängert. Die Verlängerung Ihres Abonnements führt jedoch auch zur erneuten Autorisierung Ihres Endpunkts.

• Die Häufigkeit von Autorisierungsproblemen kann sich ändern.

  Gehen Sie nicht von der Häufigkeit von Autorisierungsproblemen aus. Diese Lebenszyklusbenachrichtigungen informieren Sie, wann Sie Maßnahmen ergreifen müssen, sodass Sie nicht nachverfolgen müssen, welche Abonnements eine erneute Autorisierung erfordern. Seien Sie bereit, Autorisierungsherabforderungen von einmal alle paar Minuten für jedes Abonnement bis selten für einige Ihrer Abonnements zu bewältigen.

Reagieren auf subscriptionRemoved-Benachrichtigungen

subscriptionRemoved Lebenszyklusereignisse benachrichtigen Sie, wenn Microsoft Graph ein Abonnement entfernt hat. Wenn Sie in solchen Fällen weiterhin Änderungsbenachrichtigungen für die zugehörige Ressource erhalten möchten, müssen Sie das Abonnement neu erstellen.

Selbst wenn Sie über ein langlebiges Abonnement verfügen, können sich die Zugriffsbedingungen auf die Ressourcendaten im Laufe der Zeit ändern. Beispielsweise kann ein Ereignis im Dienst auftreten, bei dem die App den Benutzer erneut authentifizieren muss. In einem solchen Fall sendet Microsoft Graph Ihnen eine AbonnementRemoved-Benachrichtigung .

Der folgende Flow zeigt den Ablauf eines subscriptionRemoved-Ereignisses :

1. Der Dienst erkennt, dass ein Abonnement aus Microsoft Graph entfernt werden muss.

   Für diese Ereignisse gibt es keinen festgelegten Rhythmus. Sie können für einige Ressourcen häufig und für andere fast nie auftreten.

2. Microsoft Graph sendet eine subscriptionRemoved-Lebenszyklusbenachrichtigung an die lifecycleNotificationUrl (falls angegeben).

   Ab dem Zeitraum, in dem die subscriptionRemoved Lebenszyklusbenachrichtigung gesendet wurde, sind keine Lebenszyklusbenachrichtigungen verfügbar, bis die App das Abonnement erfolgreich neu erstellt hat. Die App muss diese Änderungen selbst abrufen.

Erforderliche Maßnahmen

1. Bestätigen Sie den Empfang der Lebenszyklusbenachrichtigung, indem Sie auf den POST-Aufruf mit 202 - Accepted dem Antwortcode antworten.

2. Überprüfen Sie die Echtheit der Lebenszyklusbenachrichtigung.

3. Stellen Sie sicher, dass die App über ein gültiges Zugriffstoken verfügt, um den nächsten Schritt auszuführen.

4. Erstellen Sie ein neues Abonnement.

   Diese Aktion kann fehlschlagen, da die vom System durchgeführten Autorisierungsprüfungen der App möglicherweise den Zugriff auf die Ressource verweigern. Möglicherweise muss die App ein neues Zugriffstoken abrufen, um ein Abonnement erfolgreich erneut zu authentifizieren. Sie können diese Aktionen später jederzeit wiederholen, z. B. wenn sich die Zugriffsbedingungen geändert haben.

5. Nachdem Sie das neue Abonnement erstellt haben, können Sie die Ressourcendaten synchronisieren, um fehlende Änderungsbenachrichtigungen zu identifizieren. z. B. mithilfe der Delta-Abfrage.

Reagieren auf verpasste Benachrichtigungen

missed Lifecycle-Ereignisse warnen Sie, dass einige Änderungsbenachrichtigungen möglicherweise nicht übermittelt wurden. Zum Beispiel aufgrund einer Drosselung.

Erforderliche Maßnahmen

1. Bestätigen Sie den Empfang der Lebenszyklusbenachrichtigung, indem Sie auf den POST-Aufruf mit 202 - Accepted dem Antwortcode antworten.
2. Überprüfen Sie die Echtheit der Lebenszyklusbenachrichtigung.
3. Führen Sie eine vollständige Datenneusynchronisierung der Ressource durch, um die Änderungen zu identifizieren, die nicht als Benachrichtigungen übermittelt wurden. z. B. mithilfe der Delta-Abfrage.

Verwandte Inhalte

• Abonnementressourcentyp