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 |
Hinzufügen eines Elements zum Portal | /items/add |
Alle Trigger-Ereignisse für ein bestimmtes Element | /items/<itemID> |
Löschen eines bestimmten Elements | /items/<itemID>/delete |
Aktualisieren der Eigenschaften eines bestimmten Elements | /items/<itemID>/update |
Verschieben eines Elements oder Ändern des Besitzers des Elements | /items/<itemID>/move |
Veröffentlichen eines bestimmten Elements | /items/<itemID>/publish |
Freigeben eines bestimmten Elements | /items/<itemID>/share |
Aufheben der Freigabe eines bestimmten Elements | /items/<itemID>/unshare |
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 |
Gruppe hinzufügen | /groups/add |
Alle Trigger-Ereignisse für eine bestimmte Gruppe | /groups/<groupID> |
Aktualisieren einer bestimmten Gruppe | /groups/<groupID>/update |
Löschen einer bestimmten Gruppe | /groups/<groupID>/delete |
Aktivieren von Löschschutz für eine bestimmte Gruppe | /groups/<groupID>/protect |
Deaktivieren von Löschschutz für eine bestimmte Gruppe | /groups/<groupID>/unprotect |
Einladen eines Benutzers zu einer bestimmten Gruppe | /groups/<groupID>/invite |
Hinzufügen eines Benutzers zu einer bestimmten Gruppe | /groups/<groupID>/addUsers |
Entfernen eines Benutzers aus einer bestimmten Gruppe | /groups/<groupID>/removeUsers |
Aktualisieren der Rolle eines Benutzers in einer bestimmten Gruppe | /groups/<groupID>/updateUsers |
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 |
Hinzufügen eines Benutzers zu einer Organisation | /users/add |
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 |
Löschen eines bestimmten Benutzers | /users/<username>/delete |
Aktualisieren des Profils eines bestimmten Benutzers | /users/<username>/update |
Deaktivieren des Kontos eines bestimmten Benutzers | /users/<username>/disable |
Aktivieren des Kontos eines bestimmten Benutzers | /users/<username>/enable |
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 | Type | Beschreibung |
|---|---|---|
| webhookName | Zeichenfolge | Der Name des Webhooks, von dem die Payload übermittelt wurde |
| webhookId | Zeichenfolge | Die ID des Webhooks, von dem die Payload übermittelt wurde |
| portalURL | Zeichenfolge | Die URL des Portals, bei dem der Webhook registriert ist |
| when | TIMESTAMP | Der Zeitpunkt, zu dem die Payload übermittelt wurde |
| username | Zeichenfolge | Der Benutzer, der das Ereignis ausgelöst hat |
| userId | Zeichenfolge | Die ID des Benutzers, der das Ereignis ausgelöst hat |
| when | TIMESTAMP | Der Zeitpunkt, zu dem das Ereignis eingetreten ist |
| operation | Zeichenfolge | Der vom Benutzer ausgeführte Vorgang. Dies kann einer der folgenden sein:
|
| source | Zeichenfolge | Der Elementtyp, für den der Vorgang ausgeführt wurde. Hierbei kann es sich um item, group oder user handeln. |
| id | Zeichenfolge | Die ID des Quellelements, für das der Vorgang ausgeführt wurde. |
| properties | Objekt | Zusätzliche mit dem Ereignis verknüpfte Eigenschaften. Dies kann einer der folgenden 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://machineURL/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 verwaltet werden. Führen Sie zum Erstellen eines Webhooks die folgenden Schritte aus:
- Navigieren Sie zum ArcGIS-Portalverzeichnis.https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Melden Sie sich als Administrator an.
Webhooks können nur von Administratoren erstellt und verwaltet werden.
Die Admin-Benutzer-Seite 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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Führen Sie einen Bildlauf zum unteren Bereich der Seite durch, zu Webhooks unter Untergeordnete Ressourcen.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
Verwalten von Webhooks
Sie können die Webhooks über das ArcGIS-Portalverzeichnis verwalten, indem Sie eine Anforderung im folgenden Format erstellen:
https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/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
Meine ArcGIS Enterprise-Bereitstellung 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 von Ihrem ArcGIS Enterprise Portal aus 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 schnelle 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)?
Diese Ereignisse werden nur ausgelöst, wenn sich ein Benutzer über OAuth an- oder abmeldet. Deshalb werden die integrierte Windows-Authentifizierung (IWA) und SAML nicht unterstützt. Die integrierte Sicherheit des Portals und die PKI unterstützen jedoch die An- und Abmeldeereignisse.
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.