Reduzieren fehlender Abonnements und Benachrichtigungen für Outlook-Ressourcen (Vorschau)Reduce missing subscriptions and notifications for Outlook resources (preview)

Bei Apps, die Benachrichtigungen für Outlook-Ressourcen abonnieren, können die Abonnements entfernt werden und einige Benachrichtigungen verloren gehen.Apps subscribing to notifications for Outlook resources may get their subscriptions removed and miss some notifications. Apps sollten eine Logik implementieren, um den Verlust zu erkennen und zu beheben und einen kontinuierlichen Benachrichtigungsfluss fortzusetzen.Apps should implement logic to detect and recover from the loss, and resume a continuous notification flow.

Bestimmte Ereignisse in Outlook können dazu führen, dass ein Abonnement entfernt wird.Certain events in Outlook can cause a subscription to be removed. Dazu gehören:These events include:

  • Das Kennwort eines Benutzers wurde zurückgesetztUser's password has been reset
  • Das Gerät eines Benutzers ist nicht mehr kompatibelUser's device is out of compliance
  • Das Benutzerkonto wurde gesperrtUser's account has been revoked

Bei einem solchen Ereignis sendet Outlook eine spezielle Lebenszyklusbenachrichtigung, subscriptionRemoved.When such an event happens, Outlook sends a special lifecycle notification, subscriptionRemoved.

Outlook sendet außerdem eine weitere Lebenszyklusbenachrichtigung, missed, wenn eine Benachrichtigung an eine App nicht zugestellt werden kann.Outlook also sends another lifecycle notification, missed, if a notification cannot be delivered to an app.

Eine App, die Benachrichtigungen für Outlook-Ressourcen abonniert, z. B. Nachrichten und Ereignisse, sollte die Signale subscriptionRemoved und missed überwachen:An app subscribing to notifications for Outlook resources, such as message and event, should listen to the subscriptionRemoved and missed signals:

  • Nach dem Empfangen einer subscriptionRemoved-Benachrichtigung sollte die App das Abonnement neu erstellen, um einen kontinuierlichen Fluss aufrechtzuerhalten.Upon receiving a subscriptionRemoved notification, the app should recreate the subscription in order to maintain a continuous flow.
  • Nach dem Empfangen einer missed-Benachrichtigung sollte die App Ressourcendaten mithilfe von Microsoft Graph neu synchronisieren.On receiving a missed notification, the app should resynchronize resource data using Microsoft Graph.

Um Lebenszyklusbenachrichtigungen zu erhalten, können Sie den vorhandenen notificationUrl-Endpunkt verwenden, der bereits Ressourcenbenachrichtigungen empfängt, oder Sie können eine separate lifecycleNotificationUrl registrieren, um subscriptionRemoved- und missed-Benachrichtigungen in einem separaten Endpunkt zu empfangen.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.

Erstellen eines AbonnementsCreating a subscription

Beim Erstellen eines Abonnements können Sie einen separaten Benachrichtigungsendpunkt über die lifecycleNotificationUrl-Eigenschaft festlegen.When creating a subscription, you can specify a separate notification endpoint using the lifecycleNotificationUrl property. Wenn Sie den Endpunkt festlegen, werden alle aktuellen und zukünftigen Arten von Lebenszyklusbenachrichtigungen an diesen Endpunkt zugestellt.If you specify the endpoint, all current and future types of lifecycle notifications will be delivered there. Andernfalls werden subscriptionRemoved- und missed-Benachrichtigungen für alle bestehenden Abonnements an die bestehende notificationUrl zugestellt.Otherwise, subscriptionRemoved and missed notifications will be delivered to the existing notificationUrl for all existing subscriptions.

Hinweis: Im Moment kann die lifecycleNotificationUrl-Eigenschaft nur mit der beta-Version der Microsoft Graph-APIs festgelegt oder gelesen werden.Note: At the moment, the lifecycleNotificationUrl property can only be set or read using the beta version of Microsoft Graph APIs. Abonnements, die mit beta erstellt wurden, werden jedoch in derselben Produktionsumgebung wie v1.0 gespeichert, sodass Sie den hier beschriebenen neuen Outlook-Ablauf zusätzlich zu Ihrer regulären Verwendung von v1.0 mit anderen Abonnements implementieren können.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.

Beispiel für eine AbonnementanfrageSubscription 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>"
}

Wichtig: Verwenden Sie den gleichen Hostnamen für beide Benachrichtigungs-URLs.Important: Use the same hostname for both notifications URLs.

Hinweis: Sie müssen beide Benachrichtigungsendpunkte, wie im Artikel zu generischen Benachrichtigungen beschrieben, überprüfen.Note: You need to validate both notification endpoints as described in the generic notification article. Wenn Sie beschließen, die gleiche URL für beide Endpunkte zu verwenden, erhalten Sie zwei Bestätigungsanfragen, auf die Sie antworten müssen.If you choose to use the same URL for both endpoints you will receive and respond to two validation requests.

Hinweis: Sie können die vorhandenen Abonnements nicht aktualisieren (PATCH), um die lifecycleNotificationUrl-Eigenschaft hinzuzufügen.Note: You cannot update (PATCH) the existing subscriptions to add the lifecycleNotificationUrl property. Sie sollten solche vorhandenen Abonnements entfernen und neue Abonnements erstellen und die lifecycleNotificationUrl-Eigenschaft festlegen.You should remove such existing subscriptions, and create new subscriptions and specify the lifecycleNotificationUrl property. Vorhandene Abonnements ohne die lifecycleNotificationUrl-Eigenschaft empfangen die subscriptionRemoved- und missed-Benachrichtigungen über die notificationUrl.Existing subscriptions without lifecycleNotificationUrl property will receive the subscriptionRemoved and missed notifications via the notificationUrl.

Reagieren auf subscriptionRemoved-BenachrichtigungenResponding to subscriptionRemoved notifications

Die subscriptionRemoved-Benachrichtigung informiert Sie darüber, dass ein Abonnement entfernt wurde und neu erstellt werden sollte, wenn Sie weiterhin Benachrichtigungen erhalten möchten.The subscriptionRemoved notification informs you that a subscription has been removed and should be recreated, if you want to continue receiving notifications.

Sie können ein langlebiges Abonnement erstellen (z. B. 3 Tage), und Benachrichtigungen über Ressourcendaten beginnen, an die notificationUrl zu fließen.You can create a long-lived subscription (e.g. 3 days), and resource data notifications will start flowing to the notificationUrl. Die Bedingungen für den Zugriff auf die Ressourcendaten können sich jedoch im Laufe der Zeit ändern.However, the conditions of access to the resource data may change over time. Beispielsweise kann ein Ereignis im Outlook-Dienst auftreten, das eine erneute Authentifizierung des Benutzers durch die App erfordert.For example, an event in the Outlook service may occur that requires the app to re-authenticate the user. In diesem Fall sieht der Ablauf wie folgt aus:In such a case, the flow looks as follows:

  1. Outlook erkennt, dass ein Abonnement aus Microsoft Graph entfernt werden muss.Outlook detects that a subscription needs to be removed from Microsoft Graph.

    1. Es gibt keinen eingestellten Zeitplan für diese Ereignisse.There is no set cadence for these events. Sie können für einige Ressourcen häufig und für andere fast nie auftreten.They may occur frequently for some resources, and almost never for others.
  2. Microsoft Graph sendet eine subscriptionRemoved-Benachrichtigung an die lifecycleNotificationUrl (falls angegeben), oder die notificationUrl.Microsoft Graph sends a subscriptionRemoved notification to the lifecycleNotificationUrl (if specified), or the notificationUrl.

  3. Sie können auf diese Benachrichtigung reagieren, indem Sie ein neues Abonnement für dieselbe Ressource erstellen.You can respond to this notification by creating a new subscription for the same resource. Zu diesem Zweck müssen Sie ein gültiges Zugriffstoken vorlegen, was in einigen Fällen bedeutet, dass die App den Benutzer erneut authentifizieren muss, um ein neues gültiges Zugriffstoken zu erhalten.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. Wenn Sie erfolgreich ein neues Abonnement erstellt haben, fließen die Ressourcenbenachrichtigungen wieder.If you successfully create a new subscription, resource notifications will start flowing again. Wenn die Erstellung jedoch fehlschlägt (wenn die App z. B. keinen gültigen Zugriffstoken abrufen konnte), werden keine Ressourcenbenachrichtigungen gesendet.However, if you fail (for example, the app could not obtain a valid access token), resource notifications will not be sent.

  5. Nach der Erstellung des neuen Abonnements können Sie die Ressourcendaten synchronisieren, um fehlende Änderungen zu identifizieren.After creating the new subscription, you can sync the resource data to identify any missing changes.

Beispiel für die subscriptionRemoved-BenachrichtigungsubscriptionRemoved notification example

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

Einige Punkte, die Sie bezüglich dieser Art von Benachrichtigung beachten sollten:A few things to note about this type of notification:

  • Das "lifecycleEvent": "subscriptionRemoved"-Feld kennzeichnet diese Benachrichtigung als mit dem Entfernen von Abonnements verknüpft.The "lifecycleEvent": "subscriptionRemoved" field designates this notification as related to subscription removal. Andere Arten von Lebenszyklusbenachrichtigungen sind ebenfalls möglich, und neue werden in Zukunft eingeführt.Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • Die Benachrichtigung enthält keine Informationen über eine bestimmte Ressource, da sie nicht mit einer Ressourcenänderung, sondern mit der Änderung des Abonnementstatus zusammenhängt.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.
  • Ähnlich wie bei Ressourcenbenachrichtigungen können Lebenszyklusbenachrichtigungen in einem Batch zusammengefasst werden (im value-Array), jeweils mit einem möglicherweise unterschiedlichen lifecycleEvent-Wert.Similar to resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. Verarbeiten Sie jede Benachrichtigung im Batch entsprechend.Process each notification in the batch accordingly.

Erforderliche MaßnahmenActions to take

  1. Bestätigen Sie den Empfang der Benachrichtigung, indem Sie auf den POST-Aufruf mit 202 - Accepted antwortenAcknowledge the receipt of the notification, by responding to the POST call with 202 - Accepted.
  2. Überprüfen Sie die Authentizität der Benachrichtigung.Validate the authenticity of the notification.
  3. Stellen Sie sicher, dass die App über ein gültiges Zugriffstoken verfügt, um den nächsten Schritt auszuführen.Ensure the app has a valid access token to take the next step.

Hinweis: Wenn Sie eine der Authentifizierungsbibliotheken verwenden, übernehmen diese die Aufgabe für Sie, indem sie entweder ein gültiges zwischengespeichertes Token wiederverwenden oder ein neues Token beziehen, und den Benutzer auffordern, sich erneut (z. B. mit einem neuen Kennwort) anzumelden.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). Beachten Sie, dass das Abrufen eines neuen Token fehlschlagen kann, da sich die Zugriffsbedingungen möglicherweise geändert haben und dem Aufrufer der Zugriff auf die Ressourcendaten nicht mehr gestattet ist.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. Erstellen Sie ein neues Abonnement mit dem hier beschriebenen Standardprozess.Create a new subscription using the standard process described here.

Hinweis: Diese Aktion kann fehlschlagen, da die vom System durchgeführten Autorisierungsprüfungen die App oder den Benutzerzugriff auf die Ressource verweigern können.Note: This action may fail, because the authorization checks performed by the system may deny the app or the user access to the resource. Es kann notwendig sein, dass die App ein neues Zugriffstoken vom Benutzer erhält, um ein Abonnement erfolgreich erneut zu autorisieren.It may be necessary for the app to obtain a new access token from the user to successfully reauthorize a subscription. Sie können diese Aktionen später jederzeit wiederholen, z. B. wenn sich die Zugriffsbedingungen geändert haben.You may retry these actions later, at any time, for example when the conditions of access have change. Alle Ressourcenänderungen in dem Zeitraum, in dem die Lebenszyklusbenachrichtigung gesendet wurde, bis zu dem Zeitpunkt, in dem die App das Abonnement erfolgreich neu erstellt hat, gehen verloren.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. Die App muss diese Änderungen selbstständig abrufen.The app will need to fetch those changes on its own.

  1. Nach der Erstellung des neuen Abonnements synchronisieren Sie alle fehlenden Ressourcendaten aus dem letzten bekannten Zeitpunkt, an dem Sie eine Benachrichtigung für diese Ressource erhalten haben, z.B: 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}

Reagieren auf verpasste BenachrichtigungenResponding to missed notifications

Diese Signale informieren Sie darüber, dass einige Benachrichtigungen möglicherweise nicht zugestellt wurden.These signals inform you that some notifications may have not been delivered. Sie sollten entscheiden, ob Sie diese Signale ignorieren oder behandeln.You should decide if you ignore or handle these signals.

BenachrichtigungsbeispielNotification example

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

Einige Punkte, die Sie bezüglich dieser Art von Benachrichtigung beachten sollten:A few things to note about this type of notification:

  • Das "lifecycleEvent": "missed"-Feld kennzeichnet dies als ein Signal für verpasste Benachrichtigungen.The "lifecycleEvent": "missed" field designates this as a signal about missed notifications. Andere Arten von Lebenszyklusbenachrichtigungen sind ebenfalls möglich, und neue werden in Zukunft eingeführt.Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • Die Benachrichtigung enthält keine Informationen über eine bestimmte Ressource, da sie nicht mit einer Ressourcenänderung, sondern mit der Änderung des Abonnementstatus zusammenhängt.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
  • Ähnlich wie bei Ressourcenbenachrichtigungen können Lebenszyklusbenachrichtigungen in einem Batch zusammengefasst werden (im value-Array), jeweils mit einem möglicherweise unterschiedlichen lifecycleEvent-Wert.Similar to resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. Verarbeiten Sie jede Benachrichtigung im Batch entsprechend.Process each notification in the batch accordingly.

Erforderliche MaßnahmenActions to take

  1. Bestätigen Sie den Empfang der Benachrichtigung, indem Sie auf den POST-Aufruf mit 202 - Accepted antwortenAcknowledge the receipt of the notification, by responding to the POST call with 202 - Accepted.
    • Wenn Sie diese Signale ignorieren, führen Sie keine weiteren Schritte aus.If you ignore these, signals, do nothing else. Andernfalls:Otherwise:
  2. Überprüfen Sie die Authentizität der Benachrichtigung.Validate the authenticity of the notification.
  3. Führen Sie eine vollständige erneute Datensynchronisierung der Ressource durch, um die Änderungen zu identifizieren, für die keine Benachrichtigungen zugestellt wurden.Perform a full data resync of the resource to identify the changes that were not delivered as notifications.

Zukunftssicherer Code für die Behandlung von LebenszyklusbenachrichtigungenFuture-proof the code handling lifecycle notifications

In Zukunft wird Microsoft Graph weitere Arten von Benachrichtigungen über den Lebenszyklus von Abonnements hinzufügen.In the future Microsoft Graph will add more types of subscription lifecycle notifications. Sie werden zum gleichen Endpunkt gepostet (lifecycleNotificationUrl), aber sie haben unter lifecycleEvent einen anderen Wert und können ein etwas anderes Schema und andere Eigenschaften aufweisen, die spezifisch für das Szenario sind, für das sie ausgegeben werden.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.

Sie sollten Ihren Code zukunftssicher implementieren, damit er weiterhin funktioniert, wenn Microsoft Graph neue Arten von Lebenszyklusbenachrichtigungen einführt.You should implement your code in a future-proof way so it does not break when Microsoft Graph introduces new types of lifecycle notifications. Der folgende Ansatz wird empfohlen:We recommend the following approach:

  1. Identifizieren Sie jede Benachrichtigung unter Verwendung der lifecycleEvent-Eigenschaft explizit als ein unterstütztes Ereignis.Explicitly identify each notification as an event that you support, using the lifecycleEvent property. Suchen Sie beispielsweise nach der "lifecycleEvent": "subscriptionRemoved"-Eigenschaft, um ein bestimmtes Ereignis zu identifizieren, und behandeln Sie es.For example, look for the "lifecycleEvent": "subscriptionRemoved" property to identify a specific event, and handle it.

  2. Achten Sie auf Ankündigungen von Benachrichtigungen für neue Szenarien, da es in Zukunft möglicherweise mehr Arten von Lebenszyklusbenachrichtigungen geben wird.Watch for announcements of notifications for new scenarions, as there may be more types of lifecycle notifications in the future.

  3. Ignorieren Sie in Ihrer App alle Lebenszyklusereignisse, die die App nicht erkennt, und protokollieren Sie diese, um sich genauere Einblicke zu verschaffen.In your app, ignore any lifecycle events that the app does not recognize, and log them to gain awareness.

  4. Durchsuchen Sie bei Bedarf die entsprechende Dokumentation nach neuen Lebenszyklusbenachrichtigungen, und implementieren Sie gegebenenfalls entsprechende Unterstützung.At your discretion, look up the related documentation for new lifecycle notifications and implement support for them as appropriate.

Siehe auchSee also