© Kellie L. Folkerts/Shutterstock.com
WebHooks in SharePoint

Kolumne: SharePoint ganz praktisch


Neben den klassischen serverseitigen Ereignisempfängern und den entfernten Ereignisempfängern unterstützt SharePoint seit Kurzem WebHooks. Dieser Mechanismus unterstützt ebenfalls die Benachrichtigung über Änderungen an SharePoint-Inhalten.

In den vorangegangenen Ausgaben ging es um Ereignisempfänger. Erläutert und vorgestellt wurden die klassischen Ereignisempfänger sowie die auf SharePoint-Add-ins (vormals: Apps for SharePoint) basierten. Beide Varianten bieten Möglichkeiten, um sich über Änderungen an SharePoint-Inhalten per Push-Verfahren informieren zu lassen. Mit WebHooks steht nun ein weiterer Mechanismus bereit, der einen Push-basierten Benachrichtigungsmechanismus bereitstellt. Im Gegensatz zu den beiden existierenden Ereignisempfängern unterstützen WebHooks allerdings nur bereits abgeschlossene Ereignisse, wie dass ein Listeneintrag hinzugefügt oder gelöscht wurde beispielsweise. Es findet keine Benachrichtigung statt, bevor eine Aktion ausgeführt wurde. Somit können über WebHooks auch keine anstehenden Ereignisse verhindert werden. In SharePoint stehen WebHooks erst seit Kurzem zur Verfügung, OneDrive und Outlook unterstützen WebHooks schon seit Längerem.

WebHooks

Viele weitere Systeme, u. a. auch Facebook, Google und WordPress, unterstützen WebHooks. WebHooks stellen allerdings keinen allgemeinen Standard dar, sondern beschreiben lediglich ein nicht standardisiertes Verfahren für eine Serverbenachrichtigungskommunikation. Die Hauptaufgabe von WebHooks liegt darin, über Änderungen an Ressourcen zu informieren. Im Schwerpunkt verhindert dieser Mechanismus extensive und serverbelastende Poll-Abfragen, indem die veränderte Ressource proaktiv über eine Callback-Funktion interessierte Beobachter informiert. Dazu muss sich ein Beobachter zunächst an der entsprechenden Ressource anmelden. Die Ressource trägt daraufhin die notwendigen Informationen zum Beobachter ein, um ihn im Fall von Änderungen informieren zu können. Im Fall einer Änderung prüft die Ressource alle registrierten Beobachter und benachrichtigt sie mittels einer einfachen HTTP-POST-Nachricht.

WebHooks in SharePoint

Im oberen Abschnitt wurde die allgemeine Funktionsweise von WebHooks beschrieben. Im Kontext von SharePoint stellt z. B. eine Ressource eine SharePoint-Liste dar. Das heißt, ein interessierter Beobachter kann sich über einen (WebHook-)API-Endpoint an einer SharePoint-Liste anmelden. Hierbei muss zwingend ein URL angegeben werden, an den im Fall einer Änderung Daten per POST gesendet werden. Bei SharePoint kommt hier als Besonderheit hinzu, dass registrierte WebHooks nur max. sechs Monate gültig sind. Somit muss über einen eigenen Mechanismus sichergestellt werden, dass noch benötigte WebHooks nicht versehentlich verloren gehen. SharePoint sendet an den definierten URL-Endpoint allerdings nicht direkt die konkreten Informationen in Bezug auf die Änderungen. Die Änderungsbenachrichtigung enthält lediglich Informationen über das Web und die Liste, aus der die Änderung hervorging. Zunächst geht es aber darum, den Registrierungsablauf zu erläutern. Abbildung 1 zeigt dazu die einzelnen Schritte, die für die Registrierung eines WebHooks in SharePoint durchlaufen werden müssen. Die Anmeldung erfolgt über einen HTTP-POST-Aufruf, der von der interessierten Anwendung initiiert wird. Bei dem Aufruf werden im JSON-Format die folgenden Informationen übermittelt:

  • resource
  • notificationUrl
  • expirationDateTime
image

Abb. 1: Registrierung von WebHooks in SharePoint

Mithilfe des Parameters resource wird die ID der Liste angegeben, von der Ereignisse empfangen werden sollen. Der Parameter notificationUrl enthält den Rückfruf-URL, der von SharePoint bei erkannten Änderungen an der Liste aufgerufen werden soll. Der letzte Parameter expirationDateTime definiert die Gültigkeitsdauer des WebHooks, wobei diese maximal sechs Monate in der Zukunft liegen darf. Anschließend wird der Endpoint validiert, indem von SharePoint eine zufällig generierte Zeichenkette an die Anwendung gesendet wird. Die Anwendung muss darauf reagieren und die empfangene Zeichenkette an SharePoint zurücksenden. Somit stellt SharePoint die Verfügbarkeit des WebHooks Endpoints sicher. Reagiert der WebHooks Endpoint wie erwartet, wird die Registrierung in SharePoint abgeschlossen. SharePoint sendet dann die folgenden Informationen an den Aufrufer zurück:

  • ID
  • expirationDateTime
  • notificationUrl
  • resource

Die ID enthält die eindeutige Kennung (Identifizierung) des registrierten WebHooks. Mit ihrer Hilfe kann später auf den WebHook zugegriffen werden, um beispielsweise das Ablaufdatum zu erweitern. Die anderen Werte entsprechen den bereits weiter oben erläuterten Werten. Wurden diese Schritte alle erfolgreich durchlaufen, ist der WebHook registriert und aktiv. Danach ist es wichtig, den aktuellen Änderungspunkt (ChangeToken) der SharePoint-Ressource abzufragen. Dieser Token muss anschließend gespeichert werden, z. B. in einer Azure-Datenbank, da er später für die Erkennung der letzten Änderungen benötigt wird.

Benachrichtigungen empfangen

Erfolgt nun eine Änderung in der beobachteten Ressource, informiert SharePoint die registrierten WebHook-Endpunkte. Abbildung 2 zeigt den gesamten Ablauf im Detail. Während der Benachrichtigung übermittelt SharePoint per POST-Aufruf an die registrierten...

headline from sands settings