Feedback Bearbeiten

Einrichten von Benachrichtigungen für Änderungen an Ressourcendaten

  • Artikel
  • 12 Minuten Lesedauer

Die Microsoft Graph-API verwendet einen Webhook-Mechanismus zum Übermitteln von Änderungsbenachrichtigungen an Clients. Ein Client ist ein Webdienst, der eine eigene URL zum Empfangen von Änderungsbenachrichtigungen konfiguriert. Client-Apps verwenden Änderungsbenachrichtigungen, um bei Änderungen ihren Status zu aktualisieren.

Nachdem Microsoft Graph die Abonnementsanfrage akzeptiert hat, werden Änderungsbenachrichtigungen an die im Abonnement angegebene URL gesendet. Die App führt dann Aktionen gemäß der Geschäftslogik aus. Sie ruft z. B. weitere Daten ab, aktualisiert den Zwischenspeicher und Ansichten usw.

Lernprogramm: Verwenden von Änderungsbenachrichtigungen und Nachverfolgen von Änderungen mit Microsoft Graph

Standardmäßig enthalten Änderungsbenachrichtigungen keine anderen Ressourcendaten als die id. Wenn die App Ressourcendaten anfordert, kann Sse Anrufe an Microsoft Graph-APIs durchführen, um die vollständige Ressource abzurufen. In diesem Artikel wird die Benutzer-Ressource als Beispiel für das Arbeiten mit Änderungsbenachrichtigungen verwendet.

Eine App kann auch Änderungsbenachrichtigungen abonnieren, die Ressourcendaten enthalten, um zu vermeiden, dass zusätzliche API-Aufrufe für den Datenzugriff vorgenommen werden müssen. Solche Apps müssen zusätzliche Codes einsetzen, um den Anforderungen dieser Benachrichtigungen nachzukommen, insbesondere: Antworten auf Benachrichtigungen über das Ablaufdatum von Abonnements, Überprüfung der Authentizität von Benachrichtigungen und Entschlüsselung von Ressourcendaten. Einzelheiten über die Arbeit mit diesen Benachrichtigungen finden Sie unter Änderungsbenachrichtigungen einrichten, die Ressourcendaten enthalten.

Unterstützte Ressourcen

Mit der Microsoft Graph-API kann eine App Änderungen an den folgenden Ressourcen abonnieren:

Beispielszenarien

Sie können ein Abonnement für die folgenden Szenarien erstellen:

Szenario Abfrage
Für einen bestimmten Outlook-Ordner, z. B. den Posteingang me/mailFolders('inbox')/messages
Für eine Ressource der obersten Ebene /me/messages
/me/contacts
/me/events
/users
/groups
/communications/callRecords
Für eine bestimmte Ressourceninstanz /users/{id}
/groups/{id}
/groups/{id}/conversations
/sites/{site-id}/lists/{list-id}
/communications/presences/{id}
/communications/onlinemeeting/{meeting-id}
Für einen beliebigen Ordner in der persönlichen OneDrive-Umgebung eines Benutzers /drives/{id}/root
/drives/{id}/root/subfolder
Für den Stammorder eines Sharepoint-/OneDrive for Business-Laufwerks /drive/root
Oder für eine neue Sicherheits-API-Warnung /security/alerts?$filter=status eq 'newAlert'
/security/alerts?$filter=vendorInformation/provider eq 'ASC'
Für die Tasks in der Aufgabenliste eines Benutzers /me/todo/lists/{todoTaskListId}/tasks

Azure AD-Ressourceneinschränkungen

Bestimmte Einschränkungen gelten für Azure AD-basierte Ressourcen (Benutzer, Gruppen) und rufen bei Überschreitung Fehler hervor:

Hinweis

Diese Grenzwerte gelten nicht für Ressourcen aus anderen Diensten als Azure AD. Zum Beispiel kann eine App viele weitere Abonnements für message- oder event-Ressourcen erstellen, die vom Exchange Online-Dienst als Bestandteil von Microsoft Graph unterstützt werden.

  • Maximale Abonnementkontingente:

    • Pro App (für alle Mandanten kombiniert): 50.000 Abonnements insgesamt
    • Pro Mandant (für alle Anwendungen kombiniert): 1000 Abonnements insgesamt über alle Apps hinweg
    • Pro App und Mandanten kombiniert: 100 Abonnements insgesamt

Wenn Grenzwerte überschritten werden, resultieren Versuche, ein Abonnement zu erstellen, in einer Fehlerantwort - 403 Forbidden. Die message-Eigenschaft erläutert, welcher Grenzwert überschritten wurde.

  • Azure AD B2C-Mandanten werden nicht unterstützt.

  • Änderungsbenachrichtigungen für Benutzerentitäten werden für persönliche Microsoft-Konten nicht unterstützt.

  • Es gibt ein bekanntes Problem mit Benutzer- und Gruppenabonnements.

Outlook-Ressourcenbeschränkungen

Es sind maximal 1.000 aktive Abonnements pro Postfach für alle Anwendungen zulässig.

Ressourcenbeschränkungen für Teams

Jede Teams-Ressource hat unterschiedliche Abonnement-Kontingente.

  • Für Abonnements von callRecords:

    • Pro Organisation: 100 Abonnements insgesamt

  • Für Abonnements von chatMessages (Kanäle oder Chats):

    • Pro App- und Kanal- oder Chatkombination: 1 Abonnement
    • Pro Organisation: 10.000 Abonnements insgesamt

  • Für Abonnements von Kanälen:

    • Pro App- und Teamkombination: 1 Abonnement
    • Pro Organisation: 10.000 Abonnements insgesamt

  • Für Abonnements von Chats:

    • Pro App- und Chatkombination: 1 Abonnement
    • Pro Organisation: 10.000 Abonnements insgesamt

  • Für Abonnements von Teams:

    • Pro App- und Teamkombination: 1 Abonnement
    • Pro Organisation: 10.000 Abonnements insgesamt

  • Für Abonnements von conversationMembers:

    • Pro App- und Teamkombination: 1 Abonnement
    • Pro Organisation: 10.000 Abonnements insgesamt

Gültigkeitsdauer von Abonnements

Abonnements haben eine eingeschränkte Gültigkeit. Apps müssen ihre Abonnements vor dem Ablaufzeitpunkt verlängern. Andernfalls müssen sie ein neues Abonnement erstellen. Eine Liste maximaler Ablaufzeiten finden Sie unter Maximale Abonnementdauer pro Ressourcentyp.

Apps können auch jederzeit gekündigt werden, um keine weiteren Änderungsbenachrichtigungen zu erhalten.

Verwalten von Abonnements

Clients können Abonnements erstellen, verlängern und löschen.

Erstellen eines Abonnements

Um Änderungsbenachrichtigungen für eine Ressource zu erhalten, muss in einem ersten Schritt ein Abonnement erstellt werden. Der Abonnementprozess läuft wie folgt ab:

  1. Der Client sendet eine Abonnementanforderung (POST) für eine bestimmte Ressource.

  2. Microsoft Graph überprüft die Anforderung.

    • Wenn die Anforderung gültig ist, sendet Microsoft Graph ein Überprüfungsstoken an die Benachrichtigungs-URL.
    • Wenn die Anfrage ungültig ist, sendet Microsoft Graph eine Fehlermeldung mit Code und Details.

  3. Der Client sendet das Überprüfungstoken zurück an Microsoft Graph.

  4. Microsoft Graph sendet eine Antwort an den Client zurück.

Der Client muss die Abonnement-ID speichern, um Änderungsbenachrichtigungen mit dem Abonnement korrelieren zu können.

Beispiel für eine Abonnementanfrage

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

Die Eigenschaften changeType, notificationUrl, resource und expirationDateTime sind erforderlich. Unter subscription-Ressourcentyp finden Sie die Eigenschaftsdefinitionen und Werte.

Die Eigenschaft resource gibt die Ressource an, deren Änderungen überwacht werden. Sie können z. B. ein Abonnement für einen bestimmten E-Mail-Ordner erstellen: me/mailFolders('inbox')/messages oder im Auftrag eines Benutzers mit der Zustimmung eines Administrators: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

clientState ist zwar nicht erforderlich, muss aber eingeschlossen werden, um unserem empfohlenen Prozess zum Umgang mit Änderungsbenachrichtigungen zu entsprechen. Durch das Festlegen dieser Eigenschaft können Sie bestätigen, dass die empfangenen Änderungsbenachrichtigungen vom Microsoft Graph-Dienst stammen. Aus diesem Grund muss der Wert der Eigenschaft geheim bleiben und darf nur der Anwendung und dem Microsoft Graph-Dienst bekannt sein.

Wenn der Vorgang erfolgreich war, gibt Microsoft Graph einen 201 Created-Code und ein subscription-Objekt im Textkörper zurück.

Hinweis

Jeder String-Parameter in der Abfrage, der in der Eigenschaft notificationUrl enthalten ist, wird bei der Zustellung von Benachrichtigungen in die HTTP-POST-Anforderung aufgenommen.

Endpunktprüfung für Benachrichtigungen

Microsoft Graph überprüft den Benachrichtigungsendpunkt, der in der Eigenschaft notificationUrl der Abonnementanfrage angegeben ist, bevor das Abonnement erstellt wird. Der Überprüfungsprozess läuft wie folgt ab:

  1. Microsoft Graph codiert ein Überprüfungstoken und fügt es in eine POST-Anforderung an die Benachrichtigungs-URL ein:

    Content-Type: text/plain; charset=utf-8
POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}

  2. Der Client muss die im vorhergehenden Schritt bereitgestellten validationTokenAbfrageparameter ordnungsgemäß URL-decodieren und das gesamte HTML/JavaScript mit einem Escapezeichen versehen.

    Ein Escapezeichen ist eine bewährte Methode, da böswillige Akteure den Benachrichtigungsendpunkt für websiteübergreifende Scripting-Angriffe verwenden können.

    Behandeln Sie den Wert des Überprüfungstokens im Allgemeinen als nicht transparent, da sich das Tokenformat im Allgemeinen ohne vorherige Ankündigung ändern kann. Microsoft Graph sendet niemals einen Wert, der HTML- oder JavaScript-Code enthält.

  3. Der Client muss innerhalb von 10 Sekunden nach Schritt 1 eine Antwort mit folgenden Merkmalen bereitstellen:

    • Statuscode HTTP 200 OK.
    • Inhaltstyp text/plain.
    • Ein Textkörper, der das URL-decodierte Überprüfungstoken enthält. Geben Sie einfach die gleiche Zeichenfolge zurück, die im validationTokenAbfrageparameter gesendet wurde.

    Der Client muss den Überprüfungstoken verwerfen, nachdem er in der Antwort bereitgestellt wurde.

    Wichtig

    Wenn der Client ein codiertes Überprüfungstoken zurückgibt, tritt bei der Überprüfung ein Fehler auf.

Darüber hinaus können Sie die Microsoft Graph-Postman-Sammlung verwenden, um zu bestätigen, dass Ihr Endpunkt die Überprüfungsanforderung ordnungsgemäß implementiert. Die Anforderung Abonnementüberprüfung im Ordner Misc enthält Komponententests, mit denen die vom Endpunkt bereitgestellte Antwort überprüft wird.

Testergebnisse der Validierungsantwort

Verlängern eines Abonnements

Der Kunde kann ein Abonnement mit einem bestimmten Ablaufdatum von bis zu drei Tagen ab dem Zeitpunkt der Anforderung verlängern. Die Eigenschaft expirationDateTime ist erforderlich.

Beispiel für eine Abonnementverlängerung

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

Wenn der Vorgang erfolgreich war, gibt Microsoft Graph einen 200 OK-Code und ein subscription-Objekt im Textkörper zurück. Das Abonnementobjekt enthält den neuen Wert für expirationDateTime.

Löschen eines Abonnements

Der Client kann den Erhalt von Änderungsbenachrichtigungen stoppen, indem er das Abonnement anhand seiner ID löscht.

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

Wenn der Vorgang erfolgreich verläuft, gibt Microsoft Graph einen 204 No Content-Code zurück.

Änderungsbenachrichtigungen

Wenn ein Client Änderungen an einer Ressource abonniert, sendet Microsoft Graph eine POST-Anforderung an die Benachrichtigungs-URL, sobald sich die Ressource ändert. Benachrichtigungen werden nur für die Änderungen des Typs gesendet, der im Abonnement angegeben ist, z. B. created.

Hinweis

Wenn ein Client über mehrere Abonnements verfügt, die dieselbe Ressource überwachen und die gleiche Benachrichtigungs-URL verwenden, kann Microsoft Graph mehrere Änderungsbenachrichtigungen senden, die verschiedenen Abonnements entsprechen, wobei jeweils die entsprechende Abonnement-ID angezeigt wird. Es kann nicht garantiert werden, dass alle Änderungsbenachrichtigungen in der POST-Anforderung zu einem einzelnen Abonnement gehören.

Beispiel für eine Änderungsbenachrichtigung

Dieser Abschnitt zeigt ein Beispiel für eine Benachrichtigung für die Erstellung einer Nachricht. Wenn der Benutzer eine E-Mail empfängt, sendet Microsoft Graph eine Änderungsbenachrichtigung wie die folgende: Beachten Sie, dass sich die Benachrichtigung in einer Sammlung befindet, die im value-Feld dargestellt wird. Details zur Benachrichtigungsnutzlast finden Sie unter changeNotificationCollection.

Wenn zahlreiche Änderungen vorgenommen werden, kann Microsoft Graph mehrere Benachrichtigungen senden, die verschiedenen Abonnements in derselben POST-Anforderung entsprechen.

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Verarbeiten der Änderungsbenachrichtigung

Ihr Prozess sollte alle empfangenen Änderungsbenachrichtigungen verarbeiten. Die folgenden Aufgaben müssen von der App mindestens durchgeführt werden, um eine Änderungsbenachrichtigung zu verarbeiten:

  1. Ihr Prozess sollte jede Änderungsmeldung, die er erhält, verarbeiten und einen 2xx-Klassencode senden. Wenn Microsoft Graph nicht innerhalb von 3 Sekunden einen 2xx-Klassencode erhält, wird es versuchen, die Änderungsbenachrichtigung für einen Zeitraum von etwa 4 Stunden mehrmals zu veröffentlichen; danach wird die Änderungsbenachrichtigung verworfen und nicht mehr ausgeliefert. Wenn Ihr Prozess dauerhaft nicht innerhalb von 3 Sekunden antwortet, kann es sein, dass Ihre Benachrichtigung einer Drosselung unterliegt.

    Wenn die Verarbeitung voraussichtlich länger als 3 Sekunden dauert, sollten Sie die Benachrichtigung aufrechterhalten, einen 202 - Accepted Statuscode in Ihrer Antwort an Microsoft Graph zurückgeben und dann die Benachrichtigungen verarbeiten. Wenn die Benachrichtigung nicht beibehalten wird, geben Sie einen 5xx-Klassencode zurück, um einen Fehler anzugeben, damit die Benachrichtigung wiederholt wird.

    Wenn Ihre Verarbeitung voraussichtlich weniger als 3 Sekunden dauert, sollten Sie die Benachrichtigungen verarbeiten und in Ihrer Antwort an Microsoft Graph einen 200 - OK Statuscode zurückgeben. Wenn die Benachrichtigung nicht korrekt verarbeitet wird, geben Sie einen 5xx-Klassencode zurück, um auf einen Fehler hinzuweisen, so dass die Benachrichtigung erneut versucht werden kann.

  2. Überprüfen der clientState-Eigenschaft. Sie muss dem Wert entsprechen, der ursprünglich mit der Anforderung zum Erstellen eines Abonnement übermittelt wurde.

    Hinweis

    Ist dies nicht der Fall, kann die Änderungsbenachrichtigung nicht als gültig betrachtet werden. Es ist möglich, dass die Änderungsbenachrichtigung nicht von Microsoft Graph stammt und möglicherweise von einem gefälschten Akteur gesendet wurde. Prüfen Sie auch, woher die Änderungsbenachrichtigung stammt, und ergreifen Sie die entsprechenden Maßnahmen.

  3. Aktualisieren Sie die Anwendung basierend auf Ihrer Geschäftslogik.

Wiederholen Sie den Vorgang für weitere Änderungsbenachrichtigungen in der Anfrage.

Einschränkung

Senden Sie einen 202 - Accepted Statuscode, sobald Sie die Änderungsbenachrichtigung erhalten, auch bevor Sie deren Echtheit überprüfen. Sie bestätigen lediglich den Empfang der Änderungsbenachrichtigung und verhindern unnötige Wiederholungen. Bei den meisten Abonnements gibt es keine zusätzlichen Verzögerungen bei der Veröffentlichung von Benachrichtigungen. Alle Benachrichtigungen werden innerhalb der SLA geliefert, es sei denn, bei dem Dienst liegt eine Störung vor. Wenn jedoch die URL einer Abonnement-Benachrichtigung langsam ist oder nicht antwortet, werden die Benachrichtigungen möglicherweise für den mit dem Abonnement verbundenen Host gedrosselt. Der folgende Prozess wird verwendet, um zu bestimmen, wann eine Drosselung erfolgt und wie eingeschränkte Endpunkte behandelt werden.

Benachrichtigungen werden mithilfe eines HTTP-Clients mit einem Timeout von 3 Sekunden veröffentlicht. Nach Abschluss der Veröffentlichung einer Meldung wird unabhängig vom Ergebnis die Gesamtzeit für den Versuch der Veröffentlichung, einschließlich der Netzwerklatenz, für den mit der Meldungs-URL verbundenen Host erfasst. Beträgt die Veröffentlichungszeit mehr als 2900 ms, gilt die Antwort als langsam. Die Antworten werden für den Host gesammelt, und der Prozentsatz der langsamen Antworten wird berechnet, nachdem 100 Benachrichtigungen empfangen wurden. Wenn der Prozentsatz der langsamen Antworten 10 % erreicht, wird der mit der Benachrichtigungs-URL verbundene Host als langsamer Endpunkt gekennzeichnet. Da langsame Endpunkte in der Benachrichtigungs-URL mit dem Host verknüpft sind, werden alle Benachrichtigungen für alle Abonnements, die mit dem Host verknüpft sind, für die Auswertung berücksichtigt und einer Drosselung unterzogen.

Die Auswertung wird in Echtzeit fortgesetzt. Wenn die Veröffentlichungszeit für einen Host unter 2900 ms fällt, wird diese nicht langsame Antwort in die Gesamtzahl der Antworten aufgenommen, der Prozentsatz der langsamen Antworten wird neu berechnet und der Endpunkt wird neu bewertet. Außerdem wird die Ansammlung von Antworten alle 10 Minuten geleert und die Auswertung beginnt wieder, wobei 100 Benachrichtigungen abgewartet werden, bevor ein Endpunkt ausgewertet wird. Daher erholt sich eine temporäre Latenzspitze im Netzwerk oder eine Verzögerung bei der Veröffentlichung, sobald die Verzögerung ausgeglichen ist. Eine beständigere Netzwerklatenz oder Veröffentlichungsverzögerung, die größer als 2900 ms ist, wird alle 10 Minuten kontinuierlich neu ausgewertet.

Während ein Endpunkt gedrosselt wird, werden Benachrichtigungen den folgenden zusätzlichen Verzögerungen unterzogen:

  • Die Meldungen werden automatisch an eine Gruppe von Mitarbeitern weitergeleitet, die für fehlgeschlagene und gedrosselte Meldungen zuständig sind, und es entsteht eine zusätzliche Verzögerung von 10 Minuten.
  • Benachrichtigungen werden verworfen, wenn der gedrosselte Anteil langsamer Endpunkte >= 15 % ist.
  • Benachrichtigungen, die aufgrund eines fehlgeschlagenen HTTP-Aufrufs nicht geliefert werden konnten, werden nach 10 Minuten erneut versucht.

Codebeispiele

Es folgen einige Codebeispiele in GitHub.

Firewallkonfiguration

Sie können die Firewall, die Ihre Benachrichtigungs-URL schützt, optional so konfigurieren, dass sie eingehende Verbindungen nur von Microsoft Graph zulässt. Auf diese Weise können Sie die Gefährdung durch ungültige Änderungsbenachrichtigungen, die an Ihre Benachrichtigungs-URL gesendet werden, weiter verringern. Diese ungültigen Änderungsbenachrichtigungen können versuchen, die von Ihnen implementierte benutzerdefinierte Logik auszulösen. Eine vollständige Liste der IP-Adressen, die von Microsoft Graph zur Übermittlung von Änderungsbenachrichtigungen verwendet werden, finden Sie unter Zusätzliche Endpunkte für Microsoft 365.

Hinweis

Die aufgeführten IP-Adressen, die zur Übermittlung von Änderungsbenachrichtigungen verwendet werden, können jederzeit ohne Vorankündigung aktualisiert werden.

Wartezeit

Die folgende Tabelle enthält eine Liste der voraussichtlichen Wartezeiten zwischen dem Eintreten eines Ereignisses im Dienst und der Übermittlung der Änderungsbenachrichtigung.

Ressource Durchschnittliche Wartezeit Maximale Wartezeit
alert Weniger als 3 Minuten 5 Minuten
callRecord Weniger als 15 Minuten 60 Minuten
channel Weniger als 10 Sekunden 60 Minuten
chat Weniger als 10 Sekunden 60 Minuten
chatMessage Weniger als 10 Sekunden 1 Minute
[contact][] Unbekannt Unbekannt
conversation Unbekannt Unbekannt
conversationMember Weniger als 10 Sekunden 60 Minuten
driveItem Weniger als 1 Minute 5 Minuten
event Unbekannt Unbekannt
group Weniger als 2 Minuten 15 Minuten
list Weniger als 1 Minute 5 Minuten
message Unbekannt Unbekannt
onlineMeeting Weniger als 10 Sekunden 1 Minute
presence Weniger als 10 Sekunden 1 Minute
Drucker Weniger als 1 Minute 5 Minuten
printTaskDefinition Weniger als 1 Minute 5 Minuten
team Weniger als 10 Sekunden 60 Minuten
[todoTask][] Weniger als 2 Minuten 15 Minuten
user Weniger als 2 Minuten 15 Minuten

Hinweis

Die Wartezeit, die für die Warnungs-Ressource bereitgestellt wird, gilt erst nach der Erstellung der Benachrichtigung. Sie enthält nicht die Zeit, die eine Regel benötigt, um eine Benachrichtigung aus den Daten zu erstellen.

Siehe auch