Verwenden von Webhooks zum Empfangen von Dienst-zu-Dienst-Benachrichtungen

Artikel
04/08/2023

OneDrive stellt Dienst-zu-Dienst-Benachrichtigungen über Webhooks bereit. Webhooks bieten eine einfache Benachrichtigungspipeline, damit Ihre App Änderungen am Laufwerk eines Benutzers erkennen kann, ohne den Dienst abzufragen.

Wenn Elemente, auf die Ihre App auf dem Laufwerk eines Benutzers zugreifen kann, geändert werden, wird an die von Ihnen angegebene URL eine Anforderung gesendet, in der sie darüber benachrichtigt wird, dass Änderungen aufgetreten sind.

Allgemeine Aufgaben

Aufgabe	HTTP-Methode
Neues Abonnement erstellen	`POST /subscriptions`
Delete subscription	`DELETE /subscriptions/{id}`
Abonnement aktualisieren	`PATCH /subscriptions/{id}`

Registrieren

Zum Registrieren für Webhooks fügen Sie ein neues Abonnement zu dem Element hinzu, das den Anfang des Bereichs darstellt, für den Sie über Änderungen benachrichtigt werden möchten.

Einzelheiten dazu, wie Sie eine URL für Benachrichtigungen registrieren. finden Sie unter Hinzufügen eines neuen Abonnements.

Benachrichtigungsbereich

Webhook-Benachrichtigungen werden nur für solche Änderungen an Ihre App gesendet, die die folgenden Kriterien erfüllen:

Ein Benutzer hat Ihre App zum Zugriff auf OneDrive-Inhalte autorisiert.
Die App hat Zugriff auf das Element, das die Benachrichtigung generiert.
Das Abonnement ist nicht abgelaufen.

Ihre App erhält keine Benachrichtigungen für Elemente, die für den angemeldeten Benutzer freigegeben wurden, oder für Remoteelemente auf dem Laufwerk des Benutzers, es sei denn, es werden separate Abonnements für die ursprünglichen Elemente erstellt.

Empfangen von Benachrichtigungen

Nachdem Ihr Abonnement erstellt wurde, sendet OneDrive POST-Anforderungen an die registrierte URL, wenn Elemente im Benachrichtigungsbereich geändert werden. Mehrere Benachrichtigungen an Ihren Dienst können zu einer einzigen Anforderung zusammengefasst werden, wenn für mehrere Benutzer Änderungen innerhalb des gleichen Zeitraums auftreten.

Beispielbenachrichtigung

Der Textkörper der HTTP-Anforderung an die Benachrichtigungs-URL enthält eine Webhook Benachrichtigungsressource ähnlich der folgenden.

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

Sie werden feststellen, dass die Benachrichtigung keine Informationen zu den Änderungen enthält, durch die sie ausgelöst wurde. Es wird erwartet, dass in Ihrer App das Verb delta zum Ermitteln von Änderungen an dem Status von Elementen in OneDrive und zum Speichern des syncToken-Werts für die nächste Benachrichtigung verwendet wird.

Fehlerbehandlung

Wenn beim Senden der Benachrichtigung an Ihren Dienst ein Fehler auftritt, folgt OneDrive der exponentiellen Back-off-Logik. Jede Antwort, die einen HTTP-Statuscode außerhalb des Bereichs 200-299 aufweist oder die abläuft, wird in den nächsten Minuten wiederholt. Wenn die Anforderung nach 15 Minuten nicht erfolgreich ist, wird die Benachrichtigung gelöscht.

Zukünftige Benachrichtigungen werden immer noch an Ihren Dienst gesendet, obwohl sich der Dienst vorbehält, das Abonnement zu entfernen, wenn eine ausreichende Anzahl fehlerhafter Versuche erkannt wird.

Ablauf

Für neue Abonnements wird automatisch ein Ablaufdatum bereitgestellt, wenn beim Erstellen des Abonnements kein solches Datum angegeben wird. Standardmäßig wird der Ablauf von Abonnements auf 6 Monate nach dem Erstellungsdatum festgelegt.

Bewährte Methoden

Bei der Verwendung von Webhooks sind einige wichtige Dinge zu beachten:

Dienst-zu-Dienst

Sie sollten nicht versuchen, Webhooks zum direkten Benachrichtigen von Clientgeräten zu verwenden. Jede App verfügt über eine einzige Webhook-URL, die für alle Benutzer aufgerufen wird. Diese URL sollte auf einen Dienst zeigen, der von Ihnen gesteuert wird. Sie können wählen, ob Ihr Dienst die Benachrichtigungsmitteilungen analysiert und entsprechende Pushbenachrichtigungen wie gewünscht an Client-Apps weiterleitet.

Schnell antworten

Ihre App muss innerhalb eines begrenzten Zeitrahmens auf die Anforderung antworten. Sie sollten Informationen zu Benachrichtigungsupdates in eine Warteschlange stellen und diese Anforderungen dann in einem separaten Thread verarbeiten. Sie sollten nicht versuchen, Änderungen vom OneDrive-Dienst abzurufen, bevor Sie auf die Webhook-Anforderung antworten.

Mit gleichzeitige Benachrichtigungen rechnen

In vielen Fällen erhalten Sie Benachrichtigungen für denselben Benutzer möglicherweise mehrmals in schneller Folge. Wenn ein Benutzer beispielsweise neu ist oder Inhalte in einem Batchupload nach OneDrive hochlädt, erhalten Sie möglicherweise mehrere Benachrichtigungen für denselben Benutzer, bevor Sie die erste Benachrichtigung verarbeitet haben. Stellen Sie sicher, dass die Aktionen zum Antworten auf Webhook Benachrichtigungen diesen Fall ordnungsgemäß handhaben.

Freigeben über