Einrichten von Benachrichtigungen für Änderungen der BenutzerdatenSet up notifications for changes in user data

Die Microsoft Graph-API verwendet einen Webhook-Mechanismus zum Übermitteln von Benachrichtigungen an Clients. Ein Client ist ein Webdienst, der eine eigene URL zum Empfangen von Benachrichtigungen konfiguriert. Client-Apps verwenden Benachrichtigungen, um bei Änderungen ihren Status zu aktualisieren.The Microsoft Graph API uses a webhook mechanism to deliver notifications to clients. A client is a web service that configures its own URL to receive notifications. Client apps use notifications to update their state upon changes.

Nachdem Microsoft Graph die Abonnementsanfrage akzeptiert hat, werden Pushbenachrichtigungen an die im Abonnement angegebene URL gesendet.After Microsoft Graph accepts the subscription request, it pushes notifications to the URL specified in the subscription. Die App führt dann Aktionen gemäß der Geschäftslogik aus.The app then takes action according to its business logic. Sie ruft z. B. weitere Daten ab, aktualisiert ihren Zwischenspeicher und ihre Ansichten usw.For example, it fetches more data, updates its cache and views, etc.

Unterstützte RessourcenSupported resources

Mit der Microsoft Graph-API kann eine App Änderungen an den folgenden Ressourcen abonnieren:Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

  • Outlook-[Nachricht][]Outlook message
  • Outlook-[Ereignis][]Outlook event
  • Persönlicher Outlook-KontaktOutlook personal contact
  • [Benutzer][]user
  • [Gruppe][]group
  • Office 365-[Gruppenunterhaltung][]Office 365 group conversation
  • Inhalt in der Hierarchie des driveItem-Objekts eines beliebigen Ordners auf dem persönlichen OneDrive eines BenutzersContent within the hierarchy of any folder driveItem on a user's personal OneDrive
  • Inhalt in der Hierarchie des driveItem-Objekts eines Stammordners auf OneDrive for BusinessContent within the hierarchy of the root folder driveItem on OneDrive for Business
  • [Sicherheitswarnung][]Security alert

Sie können ein Abonnement für einen bestimmten Outlook-Ordner erstellen, z.B. den Posteingang: me/mailFolders('inbox')/messagesYou can create a subscription to a specific Outlook folder such as the Inbox: me/mailFolders('inbox')/messages

Oder für eine Ressource der obersten Ebene: me/messages, me/contacts, me/events, users, oder groupsOr to a top-level resource: me/messages, me/contacts, me/events, users, or groups

Oder für eine bestimmte Ressourceninstanz: users/{id}, groups/{id}, groups/{id}/conversationsOr to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations

Oder für einen beliebigen Ordner in der persönlichen OneDrive-Umgebung eines Benutzers: /drives/{id}/root /drives/{id}/root/subfolderOr to any folder in a user's personal OneDrive: /drives/{id}/root /drives/{id}/root/subfolder

Oder für den Stammorder eines Sharepoint-/OneDrive for Business-Laufwerks: /drive/rootOr to the root folder of a SharePoint/OneDrive for Business drive: /drive/root

Oder für eine neue Sicherheits-API-Warnung: /security/alerts?$filter=status eq ‘New’, /security/alerts?$filter=vendorInformation/provider eq ‘ASC’Or to a new Security API alert: /security/alerts?$filter=status eq ‘New’, /security/alerts?$filter=vendorInformation/provider eq ‘ASC’

Azure AD-RessourceneinschränkungenAzure AD resource limitations

Bestimmte Einschränkungen gelten für Azure AD-basierte Ressourcen (Benutzer, Gruppen) und rufen bei Überschreitung Fehler hervor:Certain limits apply to Azure AD based resources (users, groups) and will generate errors when exceeded:

Hinweis: Diese Grenzwerte gelten nicht für Ressourcen aus anderen Diensten als Azure AD.Note: These limits do not apply to resources from services other than 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.For example, an app can create many more subscriptions to message or event resources, which are supported by the Exchange Online service as part of Microsoft Graph.

  • Maximale Abonnementkontingente:Maximum subscription quotas:

    • Pro App: 50 000 Abonnements insgesamtPer app: 50,000 total subscriptions
    • Pro Mandant: 1000 Abonnements insgesamt in allen AppsPer tenant: 1000 total subscriptions across all apps
    • Pro App und Mandanten kombiniert: 100 Abonnements insgesamtPer app and tenant combination: 100 total subscriptions

Wenn die Grenzwerte überschritten werden, resultieren Versuche, ein Abonnement zu erstellen, in einer Fehlerantwort - 403 Forbidden.When the limits are exceeded, attempts to create a subscription will result in an error response - 403 Forbidden. Die message-Eigenschaft erläutert, welcher Grenzwert überschritten wurde.The message property will explain which limit has been exceeded.

  • Azure AD B2C-Mandanten werden nicht unterstützt.Azure AD B2C tenants are not supported.

  • Benachrichtigungen für Benutzerentitäten werden für persönliche Microsoft-Konten nicht unterstützt.Notification for user entities are not supported for personal Microsoft accounts.

Gültigkeitsdauer von AbonnementsSubscription lifetime

Abonnements haben eine eingeschränkte Gültigkeit.Subscriptions have a limited lifetime. Apps müssen ihre Abonnements vor dem Ablaufzeitpunkt verlängern.Apps need to renew their subscriptions before the expiration time. Andernfalls müssen sie ein neues Abonnement erstellen.Otherwise, they need to create a new subscription. Eine Liste maximaler Ablaufzeiten finden Sie unter Maximale Abonnementdauer pro Ressourcentyp.For a list of maximum expiration times, see Maximum length of subscription per resource type.

Apps können auch jederzeit gekündigt werden, um keine weiteren Benachrichtigungen zu erhalten.Apps can also unsubscribe at any time to stop getting notifications.

Verwalten von AbonnementsManaging subscriptions

Clients können Abonnements erstellen, verlängern und löschen.Clients can create subscriptions, renew subscriptions, and delete subscriptions.

Erstellen eines AbonnementsCreating a subscription

Um Benachrichtigungen für eine Ressource zu erhalten, muss in einem ersten Schritt ein Abonnement erstellt werden. Der Abonnementprozess läuft wie folgt ab:Creating a subscription is the first step to start receiving notifications for a resource. The subscription process is as follows:

  1. Der Client sendet eine Abonnementanforderung (POST) für eine bestimmte Ressource.The client sends a subscription (POST) request for a specific resource.

  2. Microsoft Graph überprüft die Anforderung.Microsoft Graph verifies the request.

    • Wenn die Anforderung gültig ist, sendet Microsoft Graph ein Überprüfungsstoken an die Benachrichtigungs-URL.If the request is valid, Microsoft Graph sends a validation token to the notification URL.
    • Wenn die Anfrage ungültig ist, sendet Microsoft Graph eine Fehlermeldung mit Code und Details.If the request is invalid, Microsoft Graph sends an error response with code and details.
  3. Der Client sendet das Überprüfungstoken zurück an Microsoft Graph.The client sends the validation token back to Microsoft Graph.

  4. Microsoft Graph sendet eine Antwort an den Client zurück.The Microsoft Graph sends a response back to the client.

Der Client muss die Abonnement-ID speichern, um Benachrichtigungen mit dem Abonnement korrelieren zu können.The client must store the subscription ID to correlate notifications with the subscription.

Beispiel für eine AbonnementanfrageSubscription request example

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.The changeType, notificationUrl, resource, and expirationDateTime properties are required. Unter subscription-Ressourcentyp finden Sie die Eigenschaftsdefinitionen und Werte.See subscription resource type for property definitions and values.

Die Eigenschaft resource gibt die Ressource an, deren Änderungen überwacht werden.The resource property specifies the resource that will be monitored for changes. 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.For example, you can create a subscription to a specific mail folder: me/mailFolders('inbox')/messages or on behalf of a user given by an administrator consent: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

clientState ist zwar nicht erforderlich, muss aber eingeschlossen werden, um unserem empfohlenen Prozess zum Umgang mit Benachrichtigungen zu entsprechen.Although clientState is not required, you must include it to comply with our recommended notification handling process. Durch das Festlegen dieser Eigenschaft können Sie bestätigen, dass die empfangenen Benachrichtigungen vom Microsoft Graph-Dienst stammen.Setting this property will allow you to confirm that notifications you receive originate from the Microsoft Graph service. Aus diesem Grund muss der Wert der Eigenschaft geheim bleiben und darf nur der Anwendung und dem Microsoft Graph-Dienst bekannt sein.For this reason, the value of the property should remain secret and known only to your application and the Microsoft Graph service.

Wenn der Vorgang erfolgreich war, gibt Microsoft Graph einen 201 Created-Code und ein subscription-Objekt im Textkörper zurück.If successful, Microsoft Graph returns a 201 Created code and a subscription object in the body.

Endpunktprüfung für BenachrichtigungenNotification endpoint validation

Microsoft Graph überprüft den Benachrichtigungsendpunkt, der in der Eigenschaft notificationUrl der Abonnementanfrage angegeben ist, bevor das Abonnement erstellt wird.Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. Der Überprüfungsprozess läuft wie folgt ab:The validation process occurs as follows:

  1. Microsoft Graph sendet eine POST-Anforderung an die Benachrichtigungs-URL:Microsoft Graph sends a POST request to the notification URL:

    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    

    Wichtig: Da validationToken ein Abfrageparameter ist, muss er gemäß den HTTP-Codierungspraktiken ordnungsgemäß vom Client decodiert werden.Important: Since the validationToken is a query parameter it must be properly decoded by the client, as per HTTP coding practices. Wenn der Client das Token nicht decodiert und stattdessen im nächsten Schritt (Antwort) den codierten Wert verwendet, tritt bei der Überprüfung ein Fehler auf.If the client does not decode the token, and instead uses the encoded value in the next step (response), validation will fail. Der Client sollte den Tokenwert außerdem als nicht transparent behandeln, da sich das Tokenformat in der Zukunft möglicherweise ohne vorherige Ankündigung ändern kann.Also, the client should treat the token value as opaque since the token format may change in the future, without notice.

  2. Der Client muss innerhalb von 10 Sekunden eine Antwort mit folgenden Merkmalen bereitstellen:The client must provide a response with the following characteristics within 10 seconds:

    • Statuscode 200 (OK).A 200 (OK) status code.
    • Der Inhaltstyp muss text/plain sein.The content type must be text/plain.
    • Der Textkörper muss das von Microsoft Graph bereitgestellte Überprüfungstoken enthalten.The body must include the validation token provided by Microsoft Graph.

Der Client muss den Überprüfungstoken verwerfen, nachdem er in der Antwort bereitgestellt wurde.The client should discard the validation token after providing it in the response.

Verlängern eines AbonnementsRenewing a subscription

Der Kunde kann ein Abonnement mit einem bestimmten Ablaufdatum von bis zu drei Tagen ab dem Zeitpunkt der Anforderung verlängern.The client can renew a subscription with a specific expiration date of up to three days from the time of request. Die Eigenschaft expirationDateTime muss angegeben werden.The expirationDateTime property is required.

Beispiel für eine AbonnementverlängerungSubscription renewal example

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.If successful, Microsoft Graph returns a 200 OK code and a subscription object in the body. Das Abonnementobjekt enthält den neuen Wert für expirationDateTime.The subscription object includes the new expirationDateTime value.

Löschen eines AbonnementsDeleting a subscription

Der Client kann den Erhalt von Benachrichtigungen stoppen, indem er das Abonnement anhand seiner ID löscht.The client can stop receiving notifications by deleting the subscription using its ID.

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.If successful, Microsoft Graph returns a 204 No Content code.

BenachrichtigungenNotifications

Der Client beginnt, Benachrichtigungen zu erhalten, nachdem das Abonnement erstellt wurde.The client starts receiving notifications after creating the subscription. Microsoft Graph sendet eine POST-Anforderung an die Benachrichtigungs-URL, wenn sich die Ressource ändert.Microsoft Graph sends a POST request to the notification URL when the resource changes. Benachrichtigungen werden nur für die Änderungen des Typs gesendet, der im Abonnement angegeben ist, z. B. created.Notification are sent only for the changes of the type specified in the subscription, for example, created.

Hinweis: Wenn Sie mehrere Abonnements verwenden, die den gleichen Ressourcentyp überwachen und die gleiche Benachrichtigungs-URL verwenden, kann ein POST gesendet werden, der mehrere Benachrichtigungen mit verschiedenen Abonnement-IDs enthalten kann.Note: When using multiple subscriptions that monitor the same resource type and use the same notification URL, a POST can be sent that will contain multiple notifications with different subscription IDs. Es kann nicht garantiert werden, dass alle Benachrichtigungen in einem POST zu einem einzelnen Abonnement gehören.There is no guarantee that all notifications in the POST will belong to a single subscription.

BenachrichtigungseigenschaftenNotification properties

Das Benachrichtigungsobjekt verfügt über die folgenden Eigenschaften:The notification object has the following properties:

EigenschaftProperty TypType BeschreibungDescription
subscriptionIdsubscriptionId stringstring Die ID des Abonnements, das die Benachrichtigung generiert hat.The ID of the subscription that generated the notification.
subscriptionExpirationDateTimesubscriptionExpirationDateTime dateTimedateTime Die Ablaufzeit für das Abonnement.The expiration time for the subscription.
clientStateclientState stringstring Die clientState-Eigenschaft in der Abonnementanforderung (falls vorhanden).The clientState property specified in the subscription request (if any).
changeTypechangeType stringstring Der Ereignistyp, der die Benachrichtigung ausgelöst hat.The event type that caused the notification. Beispiel: created bei Erhalt einer E-Mail oder updated, wenn eine Nachricht als gelesen markiert wird.For example, created on mail receive, or updated on marking a message read.
resourceresource stringstring Der URI der Ressource relativ zu https://graph.microsoft.com.The URI of the resource relative to https://graph.microsoft.com.
resourceDataresourceData objectobject Der Inhalt dieser Eigenschaft hängt vom Typ der Ressource ab, die abonniert wurde.The content of this property depends on the type of resource being subscribed to.

Beispiel: Für Outlook-Ressourcen enthält resourceData die folgenden Felder:For example, for Outlook resources, resourceData contains the following fields:

EigenschaftProperty TypType BeschreibungDescription
@odata.type@odata.type stringstring Der OData-Entitätstyp in Microsoft Graph, der das dargestellte Objekt beschreibt.The OData entity type in Microsoft Graph that describes the represented object.
@odata.id@odata.id stringstring Der OData-Bezeichner des Objekts.The OData identifier of the object.
@odata.etag@odata.etag stringstring Das HTTP-Entitäts-Tag, das eine Version des Objekts darstellt.The HTTP entity tag that represents the version of the object.
idid stringstring Der Bezeichner des Objekts.The identifier of the object.

Hinweis: Der Wert id, der in resourceData bereitgestellt wird, ist zu dem Zeitpunkt gültig, zu dem die Benachrichtigung generiert wurde.Note: The id value provided in resourceData is valid at the time the notification was generated. Einige Aktionen, z. B. das Verschieben einer Nachricht in einen anderen Ordner, können dazu führen, dass die id nicht mehr gültig ist, wenn die Benachrichtigung verarbeitet wird.Some actions, such as moving a message to another folder, may result in the id no longer being valid when the notification is processed.

BenachrichtigungsbeispielNotification example

Wenn der Benutzer eine E-Mail empfängt, sendet Microsoft Graph eine Benachrichtigung wie die folgende:When the user receives an email, Microsoft Graph sends a notification like the following:

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@<tenant_guid>/messages/{long_id_string}",
      "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>"
      }
    }
  ]
}

Beachten Sie, dass das Feld value ein Array von Objekten ist.Note the value field is an array of objects. Wenn viele Benachrichtigungen in der Warteschlange stehen, sendet Microsoft Graph möglicherweise mehrere Objekte in einer einzigen Anforderung.When there are many queued notifications, Microsoft Graph may send multiple items in a single request. Benachrichtigungen aus anderen Abonnements können in dieselbe Benachrichtigungsanforderung aufgenommen werden.Notifications from different subscriptions can be included in the same notification request.

Verarbeiten der BenachrichtigungProcessing the notification

Jede Benachrichtigung, die Ihre App erhält, sollte verarbeitet werden.Each notification received by your app should be processed. Die folgenden Aufgaben müssen von der App mindestens durchgeführt werden, um eine Benachrichtigung zu verarbeiten:The following are the minimum tasks that your app must perform to process a notification:

  1. Überprüfen der clientState-Eigenschaft.Validate the clientState property. Sie muss dem Wert entsprechen, der ursprünglich mit der Anforderung zum Erstellen eines Abonnement übermittelt wurde.It must match the value originally submitted with the subscription creation request.

    Hinweis: Ist dies nicht der Fall, kann die Benachrichtigung nicht als gültig betrachtet werden.Note: If this isn't true, you should not consider this a valid notification. Es ist möglich, dass die Benachrichtigung nicht von Microsoft Graph stammt und möglicherweise von einem gefälschten Akteur gesendet wurde.It is possible that the notification has not originated from Microsoft Graph and may have been sent by a rogue actor. Prüfen Sie auch, woher die Benachrichtigung stammt, und ergreifen Sie die entsprechenden Maßnahmen.You should also investigate where the notification comes from and take appropriate action.

  2. Aktualisieren Sie die Anwendung basierend auf Ihrer Geschäftslogik.Update your application based on your business logic.

  3. Senden Sie in Ihrer Antwort an Microsoft Graph einen 202 - Accepted -Statuscode.Send a 202 - Accepted status code in your response to Microsoft Graph. Wenn Microsoft Graph keinen Code der Klasse 2xx erhält, wird versucht, die Benachrichtigung mehrmals erneut zu senden.If Microsoft Graph doesn't receive a 2xx class code, it will retry the notification a number of times.

    Hinweis: Senden Sie auch dann einen 202 - Accepted-Statuscode, wenn die Eigenschaft clientState nicht mit derjenigen übereinstimmt, die in der Abonnementanfrage übermittelt wurde.Note: You should send a 202 - Accepted status code even if the clientState property doesn't match the one submitted with the subscription request. Dies ist eine empfohlene Vorgehensweise, da sie verhindert, dass ein potenziell gefälschte Akteur die Tatsache erkennt, dass Sie seinen Benachrichtigungen nicht vertrauen. Anhand dieser Informationen versucht er dann möglicherweise, den Wert der clientState-Eigenschaft zu ermitteln.This is a good practice as it prevents a potential rogue actor from discovering the fact that you may not trust their notifications, and perhaps using that information to guess the value of the clientState property.

Wiederholen Sie den Vorgang für weitere Benachrichtigungen in der Anfrage.Repeat for other notifications in the request.

CodebeispieleCode samples

Es folgen einige Codebeispiele in GitHub.The following code samples are available on GitHub.

Siehe auchSee also