Erstellen und Verwalten von Webhooks

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	Eigenschaften
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	sharedToGroups: Wie ein Element freigegeben wird (groupID, Organization oder Everyone) Beispiele, für bessere Lesbarkeit formatiert //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
Die Freigabe eines bestimmten Elements wird aufgehoben	/items/<itemID>/unshare	unsharedFromGroups: Wie die Freigabe eines Elements aufgehoben wird (groupID, Organization oder Everyone) Beispiele, für bessere Lesbarkeit formatiert //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
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	Eigenschaften
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	invitedUserNames: Die Benutzernamen der zu einer Gruppe eingeladenen Benutzer. Beispiel, für bessere Lesbarkeit formatiert "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
Ein Benutzer wird einer bestimmten Gruppe hinzugefügt	/groups/<groupID>/addUsers	addedUserNames: Die Benutzernamen der einer Gruppe hinzugefügten Benutzer. Beispiel, für bessere Lesbarkeit formatiert "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
Ein Benutzer wird aus einer bestimmten Gruppe entfernt	/groups/<groupID>/removeUsers	removeUserNames: Die Benutzernamen der aus einer Gruppe entfernten Benutzer. Beispiel, für bessere Lesbarkeit formatiert "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
Die Rolle eines Benutzers in einer bestimmten Gruppe wird aktualisiert.	/groups/<groupID>/updateUsers	updateUserNames: Die Benutzernamen der Benutzer, deren Gruppenrollen aktualisiert wurden. Beispiel, für bessere Lesbarkeit formatiert "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
Der Besitz einer bestimmten Gruppe wurde neu zugewiesen	/groups/<groupID>/reassign
Für eine Gruppe wurde ein Element freigegeben	/groups/<groupID>/itemShare	sharedItems: itemID und Typ des Elements, das für eine Gruppe freigegeben wurde. Beispiel, für bessere Lesbarkeit formatiert "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
Die Freigabe eines Elements für eine Gruppe wurde aufgehoben	/groups/<groupID>/itemUnshare	unsharedItems: itemID und Typ des Elements, dessen Freigabe für eine Gruppe aufgehoben wurde. Beispiel, für bessere Lesbarkeit formatiert "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

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	Eigenschaften
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	userRoleUpdatedTo: Die neue Rolle, die dem Benutzer zugewiesen wurde. Beispiel, für bessere Lesbarkeit formatiert "properties": { "userRoleUpdatedTo": ["New role"] }
Einem bestimmten Benutzer wurde ein neuer Benutzertyp zugewiesen	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo: Der neue Benutzertyp, der einem Benutzer zugewiesen wurde. Beispiel, für bessere Lesbarkeit formatiert "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

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	Eigenschaften
Alle Trigger-Ereignisse für sämtliche Rollen im Portal	/roles
Eine neue Rolle wird erstellt	/roles/add	name: Der Name der Rolle, die erstellt, aktualisiert oder gelöscht wurde. Beispiel, für bessere Lesbarkeit formatiert "properties": { "name": ["New role"] }
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: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
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: sharedToGroups: Wie ein Element freigegeben wird (groupID, Organization oder Everyone) unsharedFromGroups: Wie die Freigabe eines Elements aufgehoben wird (groupID, Organization oder Everyone) removeUserNames: Die Benutzernamen der aus einer Gruppe entfernten Benutzer. updateUserNames: Die Benutzernamen der Benutzer, deren Gruppenrollen aktualisiert wurden. invitedUserNames: Die Benutzernamen der zu einer Gruppe eingeladenen Benutzer. addedUserNames: Die Benutzernamen der einer Gruppe hinzugefügten Benutzer userRoleUpdatedTo: Die neue Rolle, die dem Benutzer zugewiesen wurde. reassignedTo: Der neue Benutzer, dem ein Element oder eine Gruppe neu zugewiesen wurde. userLicenseTypeUpdatedTo: Der neue Benutzertyp, der einem Benutzer zugewiesen wurde. name: Der Name der Rolle, die erstellt, aktualisiert oder gelöscht wurde.

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:

1. Navigieren Sie zum ArcGIS-Portalverzeichnis.
   https://machine.domain.com/webadaptor/sharing/rest
2. Melden Sie sich als Administrator an.

   Webhooks können nur von Administratoren erstellt und verwaltet werden.

   Die Benutzerseite des Administrators wird angezeigt.

3. Klicken Sie auf den Hyperlink Org ID, oder erstellen Sie eine Anforderung im unten gezeigten Format, um zur Ressourcenseite "Portal Self" zu gelangen.
   https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
4. Führen Sie einen Bildlauf zum unteren Bereich der Seite durch, zu Webhooks unter Untergeordnete Ressourcen.
   https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
5. Wählen Sie unter Supported Operation Create Webhook aus.
6. 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://machine.domain.com/webadaptor/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://machine.domain.com/webadaptor/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://machine.domain.com/webadaptor/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.