Ein Webhook ist ein Mechanismus, der es einer Anwendung ermöglicht, für andere Anwendungen ereignisgesteuerte Informationen bereitzustellen. Als ArcGIS Enterprise-Portal-Administrator können Sie Webhooks erstellen, verwalten und konfigurieren. Sie können die Webhooks so konfigurieren, dass Sie automatisch benachrichtigt werden, wenn mit den Portalelementen, -gruppen und -benutzern verknüpfte Ereignisse eintreten. Nach dem Auslösen eines Webhooks erfolgt eine HTTP-Anforderung an eine eindeutige, benutzerdefinierte Payload-URL, um Informationen über das Ereignis bereitzustellen.
Wichtige Begriffe
Wichtige Begriffe im Zusammenhang mit Webhooks:
- Trigger-Ereignis: Der von Ihnen festgelegte Vorgang zum Auslösen des Webhooks. Sie können z. B. festlegen, dass der Webhook ausgelöst wird, wenn eine bestimmte Gruppe in der Organisation aktualisiert wird oder wenn ein Element freigegeben wird. Für einen Webhook können mehrere Trigger-Ereignisse vorhanden sein.
- Payload: Die Trigger-Ereignisdaten, die vom Webhook nach Eintreten des festgelegten Ereignisses übermittelt werden. Diese Informationen sind als JSON formatiert. Weitere Informationen finden Sie im nachfolgenden Abschnitt Payloads.
- Payload-URL: Die Adresse, an die die Payload-Daten gesendet werden. Die Payload-URL kann mit einem Service wie z. B. Microsoft Power Automate, Zapier oder IFTTT erstellt werden. Sie können auch mit einer Plattform Ihrer Wahl einen eigenen benutzerdefinierten Web-Service-Endpunkt erstellen.
Beispielanwendungsfall
Webhooks ermöglichen die systemübergreifende Integration von Workflows, und es gibt viele Möglichkeiten für die Nutzung von Webhooks in Ihrer Organisation.
Überwachen der Aktivitäten in ArcGIS Enterprise
Ein Webhook kann zum Überwachen der Aktivitäten in ArcGIS Enterprise verwendet werden. Sie können beispielsweise alle Ereignisse abonnieren, die mit einem bestimmten Element verknüpft sind. Der Webhook wird ausgelöst, wenn die Eigenschaften des Elements aktualisiert werden, und mit einer HTTPS-Anforderung wird eine Payload übermittelt, die Daten enthält, die das Ereignis beschreiben. Sie legen fest, wohin die Payload übermittelt wird, und können bei Empfang der Informationen entsprechend handeln.
Unterstützte Trigger-Ereignisse
Beim Erstellen des Webhooks abonnieren Sie Trigger-Ereignisse. Da diese Ereignisse Portalvorgänge sind, muss in der Webhook-Konfiguration der URI des Vorgangs angegeben werden. In den folgenden Unterabschnitten werden die verfügbaren Trigger-Ereignisse und der zugehörige URI beschrieben.
Elemente
Die Elementeigenschaften, die aktualisiert werden können, variieren je nach Elementtyp, und der /update-Vorgang wird von eindeutigen Aktionen ausgelöst. Wenn das Element z. B. eine Webkarte ist, sind das Aktualisieren des Tags, das Konfigurieren eines Pop-ups und das Ändern der Grundkarte Aktualisierungsereignisse, die den Webhook auslösen.
In der folgenden Tabelle sind die Trigger-Ereignisse für unterstützte Portalelemente, die Webkarten, Web-Apps, Layer, Pakete, PDF-Dokumente usw. umfassen, aufgeführt:
| Trigger-Ereignis | URI-Beispiel |
|---|---|
Alle Trigger-Ereignisse für sämtliche Elemente | /items |
Ein Element wird dem Portal hinzugefügt | /items/add |
Ein Element wird gelöscht | /items/delete |
Ein Element wird aktualisiert | /items/update |
Ein Element wird verschoben oder der Besitzer ändert sich | /items/move |
Ein Element wird veröffentlicht | /items/publish |
Ein Element wird freigegeben | /items/share |
Die Freigabe eines Elements wird aufgehoben | /items/unshare |
Der Besitz eines Elements wurde neu zugewiesen | /items/reassign |
Alle Trigger-Ereignisse für ein bestimmtes Element | /items/<itemID> |
Ein bestimmtes Element wird gelöscht | /items/<itemID>/delete |
Die Eigenschaften eines bestimmten Elements werden aktualisiert | /items/<itemID>/update |
Der Besitzer eines bestimmten Elements ändert sich oder das Element wird verschoben | /items/<itemID>/move |
Ein bestimmtes Element wird veröffentlicht | /items/<itemID>/publish |
Ein bestimmtes Element wird freigegeben | /items/<itemID>/share |
Die Freigabe eines bestimmten Elements wird aufgehoben | /items/<itemID>/unshare |
Der Besitz eines bestimmten Elements wurde neu zugewiesen | /items/<itemID>/reassign |
Gruppen
Alle allgemeinen Änderungen, die an den Gruppeneinstellungen vorgenommen werden, stellen eine Aktualisierung dar. Beispielsweise wird durch das Ändern des Zugriffs einer Gruppe ein Aktualisierungsereignis ausgelöst.
In der folgenden Tabelle sind die mit Gruppen verknüpften Trigger-Ereignisse aufgeführt:
| Trigger-Ereignis | URI-Beispiel |
|---|---|
Alle Trigger-Ereignisse für sämtliche Gruppen | /groups |
Eine Gruppe wird hinzugefügt | /groups/add |
Eine Gruppe wird aktualisiert | /groups/update |
Eine Gruppe wird gelöscht | /groups/delete |
Löschschutz wird für eine Gruppe aktiviert | /groups/protect |
Löschschutz wird für eine Gruppe deaktiviert | /groups/unprotect |
Ein Benutzer wird in eine Gruppe eingeladen | /groups/invite |
Ein Benutzer wird einer Gruppe hinzugefügt | /groups/addUsers |
Ein Benutzer wird aus einer Gruppe entfernt | /groups/removeUsers |
Die Rolle eines Benutzers in einer Gruppe wird aktualisiert | /groups/updateUsers |
Der Besitz einer Gruppe wurde neu zugewiesen | /groups/reassign |
Alle Trigger-Ereignisse für eine bestimmte Gruppe | /groups/<groupID> |
Eine bestimmte Gruppe wird aktualisiert | /groups/<groupID>/update |
Eine bestimmte Gruppe wird gelöscht | /groups/<groupID>/delete |
Löschschutz wird für eine bestimmte Gruppe aktiviert | /groups/<groupID>/protect |
Löschschutz wird für eine bestimmte Gruppe deaktiviert | /groups/<groupID>/unprotect |
Ein Benutzer wird in eine bestimmte Gruppe eingeladen | /groups/<groupID>/invite |
Ein Benutzer wird einer bestimmten Gruppe hinzugefügt | /groups/<groupID>/addUsers |
Ein Benutzer wird aus einer bestimmten Gruppe entfernt | /groups/<groupID>/removeUsers |
Die Rolle eines Benutzers in einer bestimmten Gruppe wird aktualisiert. | /groups/<groupID>/updateUsers |
Der Besitz einer bestimmten Gruppe wurde neu zugewiesen | /groups/<groupID>/reassign |
Benutzer
Bei jeder Änderung am Profil des Benutzers wird ein Aktualisierungsereignis ausgelöst. Änderungen an der Rolle, am Benutzertyp oder der Lizenz eines Benutzers gelten jedoch nicht als Aktualisierung des Benutzerprofils.
In der folgenden Tabelle sind die mit Benutzern verknüpften Trigger-Ereignisse aufgeführt:
| Trigger-Ereignis | URI-Beispiel |
|---|---|
Alle Trigger-Ereignisse für sämtliche Benutzer im Portal | /users |
Ein Benutzer wird der Organisation hinzugefügt | /users/add |
Ein Benutzer hat sich beim Portal angemeldet. | /users/signin |
Ein Benutzer hat sich beim Portal abgemeldet | /users/signout |
Ein Benutzer wird gelöscht | /users/delete |
Ein Benutzerprofil wird aktualisiert | /users/update |
Ein Benutzerkonto wird deaktiviert | /users/disable |
Ein Benutzerkonto wird aktiviert | /users/enable |
Einem Benutzer wurde eine neue Rolle zugewiesen | /users/updateUserRole |
Einem Benutzer wurde ein neuer Benutzertyp zugewiesen | /users/updateUserLicenseType |
Alle Trigger-Ereignisse, die mit einem bestimmten Benutzer verknüpft sind | /users/<username> |
Ein bestimmter Benutzer ist beim Portal angemeldet | /users/<username>/signIn |
Ein bestimmter Benutzer ist beim Portal abgemeldet | /users/<username>/signOut |
Ein bestimmter Benutzer wird gelöscht | /users/<username>/delete |
Ein bestimmtes Benutzerprofil wird aktualisiert | /users/<username>/update |
Ein bestimmtes Benutzerkonto wird deaktiviert | /users/<username>/disable |
Ein bestimmtes Benutzerkonto wird aktiviert | /users/<username>/enable |
Einem bestimmten Benutzer wurde eine neue Rolle zugewiesen | /users/<username>/updateUserRole |
Einem bestimmten Benutzer wurde ein neuer Benutzertyp zugewiesen | /users/<username>/updateUserLicenseType |
Rollen
Bei jeder Änderung an den Rollen in Ihrer Organisation wird ein Aktualisierungsereignis ausgelöst.
In der folgenden Tabelle sind die mit Benutzerrollen verknüpften Trigger-Ereignisse aufgeführt:
| Trigger-Ereignis | URI-Beispiel |
|---|---|
Alle Trigger-Ereignisse für sämtliche Rollen im Portal | /roles |
Eine neue Rolle wird erstellt | /roles/add |
Eine vorhandene Rolle wird aktualisiert | /roles/updated |
Eine vorhandene Rolle wird gelöscht | /roles/delete |
Payloads
Nach dem Auslösen eines Webhooks wird eine Payload im JSON-Format an die betreffende Payload-URL übermittelt. Jedes Ereignis weist ein ähnliches JSON-Schema mit für das Ereignis relevanten Informationen auf.
| Schlüssel | Typ | Beschreibung |
|---|---|---|
| webhookName | string | Der Name des Webhooks, von dem die Payload übermittelt wurde |
| webhookId | string | Die ID des Webhooks, von dem die Payload übermittelt wurde |
| portalURL | string | Die URL des Portals, bei dem der Webhook registriert ist |
| when | timestamp | Der Zeitpunkt, zu dem die Payload übermittelt wurde |
| username | string | Der Benutzer, der das Ereignis ausgelöst hat |
| userId | string | Die ID des Benutzers, der das Ereignis ausgelöst hat |
| when | timestamp | Der Zeitpunkt, zu dem das Ereignis eingetreten ist |
| operation | string | Der vom Benutzer ausgeführte Vorgang. Dies kann Folgendes sein:
|
| source | string | Der Elementtyp, für den der Vorgang ausgeführt wurde. Hierbei kann es sich um item, group oder user handeln. |
| id | string | Die ID des Quellelements, für das der Vorgang ausgeführt wurde. |
| properties | object | Zusätzliche mit dem Ereignis verknüpfte Eigenschaften. Dies kann Folgendes sein:
|
Nutzdaten-URL
Beim Erstellen eines Webhooks muss der Benutzer eine Payload-URL angeben. Diese definiert, wohin die Payload übermittelt wird. Da die Payload über eine HTTPS-POST-Anforderung übermittelt wird, muss der Webhook-Empfänger für die Kommunikation über HTTPS konfiguriert und durch das Portal erreichbar sein. Sie können mehrere Web-Services, z. B. Microsoft Power Automate, Zapier und IFFT, verwenden, um mit der Payload benutzerdefinierte Workflows zu konfigurieren. Beispielsweise können Sie einen Workflow erstellen, mit dem bei Empfang einer Payload durch Microsoft Power Automate die Payload geparst, formatiert und an einen E-Mail-Alias gesendet wird. Alternativ können Sie den Web-Service erstellen und für den Empfang von Payloads anpassen. Für Organisationen, die den Internetzugang beschränken, wird das Erstellen eines benutzerdefinierten Web-Service für den Empfang von Payloads empfohlen. Ein sofort einsatzfähiges Java-Servlet finden Sie in unseren Enterprise SDK-Beispielen.
Payload-Beispiel
Im folgenden Beispiel-Payload wird angegeben, dass eine bestimmte Gruppe aktualisiert wurde:
{
"info": {
"webhookName": "Group monitoring",
"webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
"portalURL": "https://orgURL/portal/",
"when": 1543192196521
},
"events": [{
"username": "administrator",
"userId": "173dd04b69134bdf99c5000aad0b6298",
"when": 1543192196521,
"operation": "update",
"source": "group",
"id": "173dd04b69134bdf99c5000aad0b6298",
"properties": {}
}]
}
Erstellen eines Webhooks
Webhooks können nur über das ArcGIS-Portalverzeichnis (Freigabe-API) verwaltet werden. Führen Sie zum Erstellen eines Webhooks die folgenden Schritte aus:
- Navigieren Sie zum ArcGIS-Portalverzeichnis.https://organization.domain.com/context/sharing/rest
- Melden Sie sich als Administrator an.
Webhooks können nur von Administratoren erstellt und verwaltet werden.
Die Benutzerseite des Administrators wird angezeigt.
- Klicken Sie auf den Hyperlink Org ID, oder erstellen Sie eine Anforderung im unten gezeigten Format, um zur Ressourcenseite "Portal Self" zu gelangen.https://organization.domain.com/context/sharing/rest/portals/<orgID>
- Führen Sie einen Bildlauf zum unteren Bereich der Seite durch, zu Webhooks unter Untergeordnete Ressourcen.https://organization.domain/com/context/sharing/rest/portals/<orgID>/webhooks
- Wählen Sie unter Supported Operation Create Webhook aus.
- Geben Sie die Parameter für den Webhook an.
Informationen über diese Parameter finden Sie in der REST-API-Dokumentation des Webhooks.
Ihr Webhook ist jetzt in der Liste "webhooks" enthalten: https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks
Verwalten von Webhooks
Sie können die Webhooks über das ArcGIS-Portalverzeichnis verwalten, indem Sie eine Anforderung im folgenden Format erstellen:
https://organization.domain.com/context/sharing/rest/<orgID>/webhooks/<webhookID>.
Die folgenden Vorgänge zum Verwalten von Webhooks werden unterstützt:
- Update Webhook: Aktualisieren der Parameter des Webhooks. Sie können den Namen, die Payload-URL, die Konfiguration und die Trigger-Ereignisse für den angegebenen Webhook aktualisieren.
- Delete Webhook: Entfernen des Webhooks aus dem Portal.
- Deactivate Webhook und Activate Webhook: Deaktivieren des Webhooks. Hierdurch werden beim Auslösen des Webhooks keine Payloads mehr übermittelt. Wenn der Webhook deaktiviert ist, kann mit dem Vorgang "Activate Webhook" die Übermittlung von Webhooks wieder aufgenommen werden.
Auf der Seite Notification Status werden Informationen über Trigger-Ereignisse für den betreffenden Webhook angezeigt. Sie können mithilfe dieser Tabelle den Webhook sowie Informationen über übermittelte Payloads, z. B. den Zeitpunkt des Auslösens des Webhooks, die über die Payload-URL empfangenen Antworten und die übermittelte Payload, anzeigen. Einträge, in denen die erfolgreiche Übermittlung einer Payload angegeben wird, werden nach einem Tag entfernt. Einträge, die eine fehlgeschlagene Übermittlung angeben, werden sieben Tage lang gespeichert.
Beispiele für diese Vorgänge finden Sie in der Webhooks-API.
Konfigurieren erweiterter Parameter
Es gibt mehrere erweiterte Parameter, mit denen die Webhooks weiter angepasst werden können. Diese Parameter werden auf alle konfigurierten Webhooks im Portal angewendet, und der Zugriff auf sie erfolgt über https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks/settings..
Mit dem Vorgang Update können Sie die folgenden Parameter aktualisieren:
- Number of delivery attempts: Geben Sie die Anzahl der Versuche zum Übermitteln einer Payload an. Standardmäßig erfolgen drei Versuche. Diese Anzahl kann auf bis zu fünf Versuche erhöht werden.
- Notification timeout: Geben Sie an, wie lange eine Verbindung auf den Empfang einer Antwort wartet. Wenn in diesem Intervall keine Antwort empfangen wird, erfolgt ein Timeout der Verbindung, und die Benachrichtigung gilt als fehlgeschlagen.
- Elapsed time between delivery attempts: Geben Sie die Zeit zwischen den einzelnen Versuchen der Payload-Übermittlung an. Der Standardwert ist 30 Sekunden. Er kann auf maximal 100 Sekunden erhöht oder auf bis zu 1 Sekunde verringert werden.
Weitere Informationen zum Konfigurieren erweiterter Parameter finden Sie in der Webhooks-API-Dokumentation.
Häufig gestellte Fragen zu Webhooks
Die folgenden Fragen werden bei der Verwendung von Webhooks häufig gestellt.
ArcGIS Enterprise wird in einer nicht verbundenen Umgebung hinter der Firewall meiner Organisation bereitgestellt. Kann ich trotzdem Webhooks konfigurieren?
Ja. Um Webhooks zu konfigurieren, müssen Sie eine Payload-URL verwenden, die über Ihr ArcGIS Enterprise-Portal erreichbar ist. Dazu können Sie eine benutzerdefinierte Anwendung und auf Ihrem internen Server bereitstellen.
Was löst eine Aktualisierung eines Elements, eines Benutzers oder einer Gruppe aus?
Wenn Sie Aktualisierungen für Ihre Portal-Elemente, Benutzer und Gruppen abonniert haben, wird Ihr Webhook ausgelöst, wenn deren Eigenschaften aktualisiert wurden. Wenn Sie beispielsweise Aktualisierungen für ein bestimmtes Element in Ihrem Portal abonniert haben, wird Ihr Webhook ausgelöst, sobald der Titel, die Tags oder die Miniaturansicht des Elements aktualisiert wurden. Der Netzwerkverkehr bietet Aufschluss darüber, ob eine Aktion eine Aktualisierung im Portal bewirkt. Jedes Mal, wenn eine Aktion zu einer Aktualisierung führt, kann diese Aktion auch einen Webhook auslösen, der auf Aktualisierungen wartet.
Ich verwende die integrierte Windows-Authentifizierung in meinem ArcGIS Enterprise-Portal. Kann ich trotzdem die An- und Abmeldung von Benutzern im bzw. aus dem Portal abonnieren (user/<username>/signIn)?
Ab Version 10.9 können Sie mit dem Trigger-Ereignis /signin Anmeldeereignisse für die Portal-Authentifizierung, die Authentifizierung auf Webebene und für Enterprise-Anmeldenamen erfassen.
Was passiert, wenn meine Payload-URL ausfällt oder nicht mehr verfügbar ist? Gibt es eine Möglichkeit, eine Payload wiederherzustellen, die nicht übermittelt wurde?
Wenn das Portal versucht, eine Payload an einen nicht erreichbaren oder nicht reagierenden Payload-URL- oder Webhook-Empfänger zu übermitteln, bestimmen die von Ihnen festgelegten erweiterten Parameter, wie und wann ein neuer Versuch unternommen wird. Wenn die Payload auch nach weiteren Versuchen nicht übermittelt wird, gilt dies als ein Fehler im Hinblick auf die beim Erstellen des Webhooks festgelegten deactivationPolicy. Der Webhook wird deaktiviert, sobald diese Richtlinie erfüllt ist.
Sie können zum Benachrichtigungsstatus des Webhooks wechseln, um alle Payload-Übermittlungsversuche anzuzeigen und herauszufinden, ob diese erfolgreich waren.