Übersicht über SharePoint-Webhooks

  • Artikel

SharePoint-Webhooks ermöglichen Entwicklern das Erstellen von Anwendungen, die den Empfang von Benachrichtigungen für bestimmte Ereignisse, die in SharePoint auftreten, abonnieren. Wenn ein Ereignis ausgelöst wird, sendet SharePoint ein HTTP POST-Payload an den Abonnenten. Webhooks sind leichter zu entwickeln und zu verwenden als Windows Communication Foundation-Dienste (WCF), die von SharePoint-Add-In-Remote-Ereignisempfängern verwendet werden, da Webhooks reguläre HTTP-Dienste (Web-API) sind.

Webhooks sind derzeit nur für SharePoint-Listenelemente aktiviert. Sie decken die Ereignisse ab, die bei Änderungen von Listenelementen für eine angegebe SharePoint-Liste oder eine Dokumentbibliothek ausgegeben werden. SharePoint-Webhooks bieten eine einfache Benachrichtigungspipeline, sodass Ihre Anwendung Änderungen an einer SharePoint-Liste erkennen kann, ohne den Dienst abzurufen. Weitere Informationen finden Sie unter SharePoint-Listen-Webhooks.

Erstellen von Webhooks

Um einen neuen SharePoint-Webhook zu erstellen, fügen Sie ein neues Abonnement zur entsprechenden SharePoint-Ressource hinzu, z. B. zu einer SharePoint-Liste.

Die folgenden Informationen sind für das Erstellen eines neuen Abonnements erforderlich:

  • Ressource. Die Ressourcenendpunkt-URL, für die Sie das Abonnement erstellen. Beispielsweise eine SharePoint-Listen-API-URL.
  • Server-Benachrichtigungs-URL. Die URL des Dienstendpunkts. SharePoint sendet eine HTTP-POST an diesen Endpunkt, wenn Ereignisse in der angegebenen Ressource auftreten.
  • Ablaufdatum. Das Ablaufdatum für Ihr Abonnement. Das Ablaufdatum sollte nicht mehr als 180 Tage in der Zukunft liegen. Standardmäßig wird das Ablaufdatum von Abonnements auf 180 Tage nach dem Erstellungsdatum festgelegt.

Die folgenden Informationen können Sie ebenfalls einschließen:

  • Clientzustand. Eine opake Zeichenfolge, die bei allen Benachrichtigungen zurück an den Client übergeben wird. Dies können Sie zum Überprüfen von Benachrichtigungen, zum Kategorisieren unterschiedlicher Abonnements oder aus anderen Gründen verwenden.

Behandeln von Webhook-Überprüfungsanfragen

Wenn ein neues Abonnement erstellt wird, überprüft SharePoint, ob die URL für die Benachrichtigung den Empfang von Webhook-Benachrichtigungen unterstützt. Diese Überprüfung erfolgt während der Anforderung zum Erstellen des Abonnements. Das Abonnement wird nur erstellt, wenn der Dienst in einer bestimmten Frist mit dem Überprüfungstoken antwortet.

Beispiel für Überprüfungsanforderung

Wenn ein neues Abonnement erstellt wird, sendet SharePoint eine HTTP POST-Anforderung an die eingetragene URL in einem Format ähnlich dem folgenden Beispiel:

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

Antwort

Damit das Abonnement erfolgreich erstellt wird, muss Ihr Dienst der Anforderung durch Zurückgeben des ValidationToken-Abfragezeichenfolgenparameters als Nur-Text-Antwort antworten.

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

Wenn Ihre Anwendung einen anderen Statuscode als 200 zurückgibt oder nicht mit dem Wert des ValidationToken-Parameters antwortet, schlägt die Anforderung zum Erstellen eines neuen Abonnements fehl.

Empfangen von Benachrichtigungen

Die Benachrichtigungsnutzlast informiert die Anwendung darüber, dass in einer bestimmten Ressource für ein bestimmtes Abonnement ein Ereignis aufgetreten ist. Mehrere Benachrichtigungen an Ihre Anwendung können in einer einzigen Anforderung zusammengefasst werden, falls in der Ressource innerhalb desselben Zeitraums mehrere Änderungen vorgenommen wurden.

Die Benachrichtigungsnutzlast enthält im Textteil außerdem den Clientzustand, sofern Sie ihn beim Erstellen des Abonnements verwendet haben.

Webhook-Benachrichtigungsressource

Die Benachrichtigungsressource definiert die Form der Daten, die Ihrem Dienst bereitgestellt werden, wenn eine SharePoint-Webhook-Benachrichtigungsanforderung an die registrierte Benachrichtigungs-URL gesendet wird.

JSON-Darstellung

Jede vom Dienst generierte Benachrichtigung wird in eine WebhookNotification-Instanz serialisiert:

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

Da in einer einzigen Anforderung mehrere Benachrichtigungen an den Dienst gesendet werden können, werden diese in einem Objekt mit einem einzigen Array-Wert zusammengefasst:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

Eigenschaften

Eigenschaftenname Typ Beschreibung
resource String Eindeutige ID der Liste, in der das Abonnement registriert ist.
subscriptionId String Der eindeutige Bezeichner für die Abonnementressource.
clientState String - optional Ein optionaler Zeichenfolgenwert, der in der Benachrichtigungsmitteilung für dieses Abonnement zurückgegeben wird.
expirationDateTime DateTime Datum und Uhrzeit des Ablaufs des Abonnements, wenn dies nicht aktualisiert oder erneuert wird.
tenantId String Eindeutige ID für den Mandanten, der diese Benachrichtigung generiert hat.
siteUrl String Server-relative URL der Website, auf der das Abonnement registriert wurde.
webId String Eindeutige ID des Webs, in dem das Abonnement registriert wurde.

Beispielbenachrichtigung

Der Hauptteil der HTTP-Anforderung an die Dienstbenachrichtigungs-URL enthält eine Webhook-Benachrichtigung. Das folgende Beispiel zeigt eine Nutzlast mit einer Benachrichtigung:

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

Die Benachrichtigung umfasst keine Informationen zu den Änderungen, durch die sie ausgelöst wurde. Ihre Anwendung verwendet die GetChanges-API in der Liste, um die Sammlung von Änderungen aus dem Änderungsprotokoll abzufragen und den Änderungstokenwert für alle nachfolgenden Aufrufe zu speichern, wenn die Anwendung benachrichtigt wird.

Ereignistypen

SharePoint-Webhooks unterstützen nur asynchrone Ereignisse. Dies bedeutet, dass Webhooks erst ausgelöst werden, nachdem eine Änderung stattgefunden hat (ähnlich wie bei -ed-Ereignissen ), und daher sind synchrone Ereignisse (-ing ) nicht möglich.

Fehlerbehandlung

Wenn beim Senden der Benachrichtigung an Ihre Anwendung ein Fehler auftritt, versucht SharePoint bis zu 5 Mal, die Benachrichtigung zuzustellen. Jede Antwort, die einen HTTP-Statuscode außerhalb des Bereichs 200-299 aufweist oder die abläuft, wird in 5 Minuten erneut versucht. Wenn die Anforderung nach 5 Versuchen nicht erfolgreich ist, wird die Benachrichtigung gelöscht. Weitere Benachrichtigungen an Ihre Anwendung werden weiterhin ausgeführt.

Ablauf

Webhook-Abonnements laufen standardmäßig nach 180 Tagen ab, wenn kein ExpirationDateTime-Wert angegeben wird.

Sie müssen beim Erstellen des Abonnements ein Ablaufdatum festlegen. Das Ablaufdatum sollte weniger als 180 Tage betragen. Die Anwendung sollte das Ablaufdatum entsprechend den Anforderungen Ihrer Anwendung behandeln, indem das Abonnement regelmäßig aktualisiert wird.

Wiederholungsmechanismus

Wenn ein Ereignis in SharePoint auftritt und Ihr Dienstendpunkt nicht erreichbar ist (z. B. aufgrund von Wartungen), wiederholt SharePoint das Senden der Benachrichtigung. SharePoint führt 5 Wiederholungen mit 5 Minuten Wartezeit zwischen den Versuchen durch. Wenn Ihr Dienst länger ausfällt, werden die in diesem Zeitraum verpassten Änderungen durch den Aufruf von GetChanges() wiederhergestellt, sobald der Dienst wieder verfügbar ist und von Sharepoint aufgerufen wird.