Empfangen von Änderungsbenachrichtigungen über Webhooks

Ein Webhook ist eine HTTP-basierte benutzerdefinierte Rückruf-API, die Sie in Ihrer Infrastruktur einrichten können, um Änderungsbenachrichtigungen und Ereignisse von einem Dienst wie Microsoft Graph zu empfangen. Um Webhooks verwenden zu können, müssen Sie einen öffentlich zugänglichen HTTPS-gesicherten Endpunkt definieren, der die Benachrichtigungen empfängt.

Sie können ein Abonnement für die Ressource erstellen, für die Sie über Änderungen benachrichtigt werden möchten. Solange das Abonnement gültig ist, sendet Microsoft Graph eine Benachrichtigung an Ihren Endpunkt, wenn eine Änderung an der Ressource erkannt wird.

Der Artikel führt Sie durch den Prozess der Implementierung Ihres Webhook-Endpunkts, das Abonnieren und Verwalten von Microsoft Graph-Abonnements und das Empfangen von Änderungsbenachrichtigungen über Webhooks.

Ausführliche Informationen zum Erstellen von Änderungsbenachrichtigungen finden Sie unter Microsoft Graph-API Änderungsbenachrichtigungen.

Überlegungen zu einem Webhookendpunkt

Bevor Sie eine Benachrichtigung über Webhooks erhalten können, müssen Sie einen öffentlich zugänglichen, HTTPS-gesicherten Endpunkt erstellen, der über eine URL adressierbar ist. Wenn Ihr Endpunkt nicht öffentlich zugänglich ist, sendet Microsoft Graph keine Benachrichtigungen an Ihren Endpunkt.

Ihr Endpunkt muss korrekte, konsistente und zeitnahe HTTP-Antworten bereitstellen, um Benachrichtigungen zuverlässig empfangen zu können. Wenn ein Endpunkt nicht rechtzeitig antwortet, beginnt der Änderungsbenachrichtigungsdienst möglicherweise, Benachrichtigungen zu löschen. Verworfene Benachrichtigungen können nicht wiederhergestellt werden.

Ihr Endpunkt muss auch weiterhin bei Microsoft Graph authentifiziert bleiben, entweder durch kontinuierliche Verlängerung Ihres Abonnements oder durch Reagieren auf Lebenszyklusbenachrichtigungen.

HTTP-Codes und Wiederholungslogik

Sobald der Microsoft Graph-Änderungsbenachrichtigungsdienst einen 2xx-Klassencode von Ihrem Endpunkt empfängt, gilt die Benachrichtigung als gesendet. Solange der Änderungsbenachrichtigungsdienst innerhalb von 10 Sekunden eine andere HTML-Antwort (sogar einen Fehlercode) empfängt, versucht der Dienst, die Benachrichtigung für bis zu vier Stunden zu übermitteln.

• Wenn Sie die Benachrichtigung innerhalb eines 3-Sekunden-Fensters verarbeiten können, sollten Sie einen 200 - OK status Code an Microsoft Graph zurückgeben.
• Wenn ihr Dienst mehr als 10 Sekunden benötigt, um die Benachrichtigung zu verarbeiten, können Sie die Benachrichtigung in einer Warteschlange an Ihrem Endpunkt beibehalten und status Code an Microsoft Graph zurückgeben 202 - Accepted .
• Wenn die Benachrichtigung nicht verarbeitet oder in die Warteschlange gestellt wird, geben Sie einen 5xx-Klassencode zurück, um einen Fehler anzugeben, damit Microsoft Graph die Benachrichtigung wiederholen kann.

Benachrichtigungen, die nicht übermittelt werden können, werden in exponentiellen Backoffintervallen wiederholt. Verpasste Benachrichtigungen können bis zu 4 Stunden dauern, bis sie erneut gesendet werden, sobald Ihr Endpunkt online geschaltet wird.

Einschränkung

Aus Sicherheits- und Leistungsgründen drosselt Microsoft Graph Benachrichtigungen, die an Endpunkte gesendet werden, die langsam oder nicht mehr reagieren. Es kann sein, dass Benachrichtigungen so gelöscht werden, dass sie nicht wiederhergestellt werden können.

1. Ein Endpunkt wird als "langsam" gekennzeichnet, sobald mehr als 10 % der Antworten länger als 10 Sekunden in einem 10-Minuten-Zeitfenster dauern.

   • Sobald ein Endpunkt als "langsam" gekennzeichnet ist, werden alle neuen Benachrichtigungen mit einer Verzögerung von 10 Sekunden gesendet.
   • Ein Endpunkt beendet den "langsamen" Zustand, sobald weniger als 10 % der Antworten länger als 10 Sekunden in einem 10-minütigen Zeitfenster dauern.

2. Ein Endpunkt wird als "Löschen" markiert, sobald mehr als 15 % der Antworten länger als 10 Sekunden in einem Zehn-Minuten-Zeitfenster dauern.

   • Sobald ein Endpunkt als "löschen" gekennzeichnet ist, werden alle neuen Benachrichtigungen für bis zu 10 Minuten gelöscht.
   • Ein Endpunkt beendet den Zustand "Löschen", sobald weniger als 15 % der Antworten in einem Zehn-Minuten-Fenster länger als 10 Sekunden dauern.

Wenn Ihr Endpunkt diese Leistungsmerkmale nicht erfüllen kann, erwägen Sie die Verwendung von Event Hubs oder Event Grid als Ziel für den Empfang von Benachrichtigungen.

Authentifizierung

Wenn Sie Ihr Abonnement erstellen, wird ein Zugriffstoken an Ihren Endpunkt gesendet. Dieses Zugriffstoken wird nur verwendet, um die Gültigkeit Ihres Endpunkts zu überprüfen, und weist einen anderen Lebenszyklus als ihr Änderungsbenachrichtigungsabonnement auf. Dieses Zugriffstoken läuft in der Regel innerhalb einer Stunde ab.

Ihr Endpunkt muss darauf vorbereitet sein, regelmäßig von Microsoft Graph erneut autorisiert zu werden, um sicherzustellen, dass Microsoft Graph weiterhin Benachrichtigungen an Ihren Endpunkt senden kann.

Wenn ein Zugriffstoken abläuft, werden keine Benachrichtigungen zugestellt. Es löst jedoch kein Endpunktdrosselungsverhalten aus, und Microsoft Graph versucht weiterhin, jede Benachrichtigung bis zu vier Stunden lang zu senden. Wenn das Zugriffstoken also innerhalb von vier Stunden nach Ablauf aktualisiert wird, werden nicht gesendete Benachrichtigungen übermittelt.

Es wird empfohlen, Ihrem Abonnement Lebenszyklusbenachrichtigungen hinzuzufügen, um eine Warnung zum Tokenablauf zu erhalten, damit Sie Ihren Endpunkt rechtzeitig erneut authentifizieren können.

Wenn Sie Ihr Abonnement verlängern, wird auch Ihr Zugriffstoken aktualisiert.

Firewallkonfiguration

Sie können die Firewall, die Ihren Endpunkt schützt, so konfigurieren, dass nur eingehende Verbindungen von Microsoft Graph zugelassen werden, wodurch die Gefährdung durch ungültige Änderungsbenachrichtigungen weiter reduziert wird. 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.

Erstellen eines Abonnements

Wichtig

Es sind mehrere Schritte erforderlich, um sicherzustellen, dass ein sicherer Kommunikationskanal zwischen dem Microsoft Graph-Änderungsbenachrichtigungsdienst und Ihrem Endpunkt eingerichtet und verwaltet wird.

Um Microsoft Graph-Änderungsbenachrichtigungen zu erhalten, müssen Sie ein Abonnement erstellen, indem Sie die URL Ihres Endpunkts (Benachrichtigungs-URL) verwenden, um das Abonnement einzurichten. Das Muster zum Einrichten eines Abonnements sieht wie folgt aus:

1. Die Client-App sendet eine Abonnementanforderung zum Abonnieren von Änderungen an einer bestimmten Ressource.

2. Microsoft Graph überprüft die Anforderung.

   • Wenn die Anforderung gültig ist, sendet Microsoft Graph ein Validierungstoken an die Benachrichtigungs-URL für die Client-App, um die Benachrichtigungs-URL zu überprüfen.
   • Wenn die Anforderung ungültig ist, sendet Microsoft Graph eine Fehlerantwort mit einem Fehlercode und Details.

3. Wenn der Client die Überprüfungsanforderung für die Benachrichtigungs-URL empfängt, antwortet der Client mit dem Validierungstoken im Klartext.

4. Microsoft Graph überprüft die Antwort des Client-Validierungstokens, und wenn das Validierungstoken gültig ist, antwortet mit einer Abonnement-ID.

Abonnementanforderung

Die Client-App sendet eine POST-Anforderung an den /subscriptions Endpunkt. Das folgende Beispiel zeigt eine einfache Anforderung zum Abonnieren von Änderungen an einem bestimmten E-Mail-Ordner im Namen des angemeldeten Benutzers. Weitere Informationen zu anderen Microsoft Graph-Ressourcen, die Änderungsbenachrichtigungen unterstützen, finden Sie unter Unterstützte Ressourcen.

HTTP

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-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/notificationClient",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/me/mailfolders('inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-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);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

CLI

mgc subscriptions create --body '{\
  "changeType": "created,updated",\
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",\
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",\
  "resource": "/me/mailfolders('inbox')/messages",\
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",\
  "clientState": "SecretClientState"\
}\
'

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Go

// 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/notificationClient"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/me/mailfolders('inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "SecretClientState"
requestBody.SetClientState(&clientState) 

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

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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/notificationClient");
subscription.setLifecycleNotificationUrl("https://webhook.azurewebsites.net/api/lifecycleNotifications");
subscription.setResource("/me/mailfolders('inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-03-20T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("SecretClientState");
Subscription result = graphClient.subscriptions().post(subscription);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/notificationClient',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/me/mailfolders(\'inbox\')/messages',
  expirationDateTime: '2016-03-20T11:00:00.0000000Z',
  clientState: 'SecretClientState'
};

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

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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/notificationClient');
$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');
$requestBody->setResource('/me/mailfolders(\'inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-03-20T11:00:00.0000000Z'));
$requestBody->setClientState('SecretClientState');

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

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/notificationClient"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/me/mailfolders('inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-03-20T11:00:00.0000000Z")
	clientState = "SecretClientState"
}

New-MgSubscription -BodyParameter $params

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Python

# 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://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created,updated",
	notification_url = "https://webhook.azurewebsites.net/notificationClient",
	lifecycle_notification_url = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	resource = "/me/mailfolders('inbox')/messages",
	expiration_date_time = "2016-03-20T11:00:00.0000000Z",
	client_state = "SecretClientState",
)

result = await graph_client.subscriptions.post(request_body)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Die clientState-Eigenschaft ist erforderlich. Durch Festlegen der -Eigenschaft kann Ihr Dienst bestätigen, dass Änderungsbenachrichtigungen, die Sie erhalten, von Microsoft Graph 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.

Jedes Abonnement verfügt über eine eindeutige subscriptionId, auch wenn Sie über mehrere Abonnements verfügen, die dieselbe Ressource überwachen und dieselbe Benachrichtigungs-URL verwenden.

Hinweis

Alle Abfragezeichenfolgenparameter, die in der notificationUrl-Eigenschaft enthalten sind, sind in der HTTP POST-Anforderung enthalten, wenn Benachrichtigungen an Ihren Dienst übermittelt werden.

Doppelte Abonnements sind nicht zulässig. Wenn eine Abonnementanforderung die gleichen Werte für changeType und ressource wie ein vorhandenes Abonnement enthält, schlägt die Anforderung mit einem HTTP-Fehlercode 409 Conflictund der Fehlermeldung Subscription Id <> already exists for the requested combinationfehl.

notificationUrl-Überprüfung

Wenn Sie eine Anforderung zum Erstellen eines Abonnements senden, um Änderungsbenachrichtigungen über Webhooks zu erhalten, überprüft der Abonnementdienst, ob die notificationUrl-Eigenschaft in Ihrer Abonnementanforderung gültig ist. Der Validierungsprozess funktioniert wie folgt:

Hinweis

Wenn Sie auch Lebenszyklusbenachrichtigungen abonnieren, überprüft der Abonnementdienst auch lifecycleNotificationUrl.

1. Wenn ein Abonnement angefordert wird, codiert Microsoft Graph ein Validierungstoken und schließt es wie folgt 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 URL ordnungsgemäß decodieren, um das Nur-Text-Validierungstoken von Microsoft Graph abzurufen.

   Das Escapen von HTML- oder JavaScript-Code ist eine bewährte Methode, da böswillige Akteure den Benachrichtigungsendpunkt für websiteübergreifende Skripts verwenden können. Microsoft Graph sendet niemals einen Wert, der HTML- oder JavaScript-Code enthält.

   Im Allgemeinen sollten Sie den Wert des Validierungstokens als undurchsichtig behandeln, da sich das Tokenformat ohne Vorheriges ändern kann.

3. Der Client muss innerhalb von 10 Sekunden nach Schritt 1 mit den folgenden Merkmalen antworten:

   • Statuscode HTTP 200 OK.
   • Inhaltstyp text/plain.
   • Ein Text, der das URL-decodierte Nur-Text-Validierungstoken enthält.

   Wichtig

   Das Validierungstoken muss als Nur-Text zurückgegeben werden. Wenn der Client ein codiertes Überprüfungstoken zurückgibt, tritt bei der Überprüfung ein Fehler auf.

4. Wenn die Endpunktüberprüfung fehlschlägt, erstellt Microsoft Graph das Abonnement nicht.

Empfangen von Benachrichtigungen

Während das Abonnement gültig ist und Änderungen an der Ressource vorliegen, die Sie abonniert haben, sendet Microsoft Graph eine POST Anforderung mit Details zu den Änderungen an notificationUrl . Diese Nutzlast ist die Änderungsbenachrichtigung.

Bei den meisten Abonnements verzögert Microsoft Graph das Senden von Benachrichtigungen nicht, sondern übermittelt alle Benachrichtigungen innerhalb der SLA, es sei denn, es tritt ein Vorfall auf.

Eine Änderungsbenachrichtigungsnutzlast, die an Ihren Endpunkt gesendet wird, kann eine Sammlung von Änderungsbenachrichtigungen für Ihre Abonnements enthalten.

Beispiel für eine Änderungsbenachrichtigung

Wenn der Benutzer eine E-Mail erhält, sendet Microsoft Graph ein Änderungsbenachrichtigungsobjekt an die Client-App, wie im folgenden Beispiel gezeigt. Weitere Informationen zur Benachrichtigungsnutzlast finden Sie unter changeNotificationCollection und die zugehörige changeNotification .

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

Wenn Sie eine Änderungsbenachrichtigung erhalten:

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

   Wenn ein Konflikt vorliegt, betrachten Sie die Änderungsbenachrichtigung nicht als gültig. Es ist möglich, dass die Änderungsbenachrichtigung nicht von Microsoft Graph stammt und möglicherweise von einem nicht autorisierten Akteur gesendet wurde. Prüfen Sie auch, woher die Änderungsbenachrichtigung stammt, und ergreifen Sie die entsprechenden Maßnahmen.

2. Aktualisieren Sie Ihre Client-App basierend auf Ihrer Geschäftslogik.

Abonnementlebenszyklus

Wenn sie nicht mehr benötigt werden, werden Abonnements möglicherweise gelöscht oder laufen ab. Wenn Sie Ihr Abonnement erstellen, legen Sie mithilfe der expirationDateTime-Eigenschaft ein Ablaufdatum fest. Sobald diese Zeit verstreicht, löscht Microsoft Graph das Abonnement und sendet keine Benachrichtigungen an Ihren Endpunkt. Sie können Ihr Abonnement auch explizit löschen.

Die einfachste Möglichkeit, weiterhin Benachrichtigungen zu erhalten, besteht darin, Ihre Abonnementanforderung weiterhin zu verlängern. Jede Benachrichtigung enthält eine subscriptionExpirationDateTime-Eigenschaft . Sie können es verwenden, um Ihnen zu helfen, wann Sie Ihr Abonnement verlängern müssen.

Jedes Abonnement enthält auch ein Zugriffstoken, das dem Endpunkt gewährt wird. Die Ablaufzeit dieses Zugriffstokens kann vor dem Ablauf des Abonnements auftreten. Sie können den Ablauf von Zugriffstoken mithilfe von Lebenszyklusbenachrichtigungen für Ihr Abonnement verwalten.

Verlängern eines Abonnements

HTTP

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

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

C#

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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-22T11:00:00.0000000Z"),
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

CLI

mgc subscriptions patch --subscription-id {subscription-id} --body '{\
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"\
}\
'

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Go

// 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()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-22T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().BySubscriptionId("subscription-id").Patch(context.Background(), requestBody, nil)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-03-22T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
Subscription result = graphClient.subscriptions().bySubscriptionId("{subscription-id}").patch(subscription);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  expirationDateTime: '2016-03-22T11:00:00.0000000Z'
};

await client.api('/subscriptions/{id}')
	.update(subscription);

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PHP

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


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

$requestBody = new Subscription();
$requestBody->setExpirationDateTime(new \DateTime('2016-03-22T11:00:00.0000000Z'));

$result = $graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->patch($requestBody)->wait();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	expirationDateTime = [System.DateTime]::Parse("2016-03-22T11:00:00.0000000Z")
}

Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Python

# 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://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	expiration_date_time = "2016-03-22T11:00:00.0000000Z",
)

result = await graph_client.subscriptions.by_subscription_id('subscription-id').patch(request_body)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Wenn die Anforderung zur Abonnementverlängerung erfolgreich ist, gibt Microsoft Graph einen 200 OK Antwortcode und ein Abonnementobjekt im Antworttext zurück. Das Abonnementobjekt enthält den neuen expirationDateTime-Wert .

Löschen eines Abonnements

Wenn die Client-App keine Änderungsbenachrichtigungen mehr wünscht, kann sie das Abonnement mit ihrer subscriptionId wie folgt löschen:

HTTP

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

C#

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Subscriptions["{subscription-id}"].DeleteAsync();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

CLI

mgc subscriptions delete --subscription-id {subscription-id}

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Go

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

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


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Subscriptions().BySubscriptionId("subscription-id").Delete(context.Background(), nil)

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.subscriptions().bySubscriptionId("{subscription-id}").delete();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/subscriptions/{id}')
	.delete();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


$graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->delete()->wait();

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

Remove-MgSubscription -SubscriptionId $subscriptionId

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.subscriptions.by_subscription_id('subscription-id').delete()

In der SDK-Dokumentation finden Sie ausführliche Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.

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

Lebenszyklusbenachrichtigungen für Ihr Abonnement

Um mehr Flexibilität und Zuverlässigkeit zu erzielen, können Sie beim Erstellen eines Abonnements auch die Lebenszyklusbenachrichtigungen für dieses Abonnement abonnieren, indem Sie einen lifecycleNotificationUrl-Endpunkt bereitstellen, der Lebenszyklusbenachrichtigungen empfängt, verarbeitet und darauf reagiert.

Wenn Sie Lebenszyklusbenachrichtigungen abonnieren, warnt Microsoft Graph Sie:

• Wenn das Zugriffstoken bald abläuft.
• Wenn ein Abonnement bald abläuft.
• Wenn ein Mandantenadministrator ihre App-Berechtigungen zum Lesen einer Ressource widerruft.

Hinweis

Wenn ein Zugriffstoken abläuft, werden keine Benachrichtigungen an den Endpunkt übermittelt. Microsoft Graph versucht jedoch weiterhin, jede Benachrichtigung für bis zu vier Stunden zu senden. Wenn das Zugriffstoken also innerhalb von vier Stunden nach Ablauf aktualisiert wird, werden nicht gesendete Benachrichtigungen übermittelt.

Weitere Informationen zur Verwendung von Lebenszyklusbenachrichtigungen für Ihr Abonnement finden Sie unter Lebenszyklusbenachrichtigungen.

Zusammenfassung

In diesem Artikel haben Sie erfahren, wie Sie Änderungsbenachrichtigungen über Webhooks erhalten.

1. Erstellen Sie ein Abonnement, indem Sie eine POST-Anforderung an den /subscriptions Endpunkt senden.
2. Microsoft Graph überprüft den Webhook-Benachrichtigungsendpunkt, bevor er den Erstellungsprozess des Abonnements abgeschlossen hat. Eine eindeutige subscriptionID ist mit dem Abonnement verknüpft.
3. Solange das Abonnement noch gültig ist und Änderungen an der abonnierten Ressource auftreten, sendet Microsoft Graph Änderungsbenachrichtigungen an den notificationUrl-Endpunkt .
4. Verlängern Sie das Abonnement regelmäßig, um seine Gültigkeit zu behalten und weiterhin Updates zu den abonnierten Änderungen zu erhalten.

Verwandte Inhalte

• Abonnementressourcentyp
• changeNotificationCollection-Ressourcentyp
• Lebenszyklus: Benachrichtigungen