Automatisieren von Notebook-Workflows mit Webhook-Ereignissen

Ein Webhook ist ein Mechanismus, der es einer Anwendung ermöglicht, für andere Anwendungen ereignisgesteuerte Informationen bereitzustellen. Webhooks können auf Organisations- und Serviceebene konfiguriert werden, um ein Notebook automatisch auszuführen, wenn Ereignisse im Zusammenhang mit Ihrer Organisation oder Ihren Services auftreten.

Automatisieren eines Notebooks mithilfe von Organisations-Webhooks

Als ArcGIS Enterprise-Administrator oder als Benutzer mit der Berechtigung für Organisations-Webhooks können Sie Webhooks erstellen, verwalten und konfigurieren. Sie können Webhooks so konfigurieren, dass ein Notebook, dessen Besitzer Sie sind, automatisch ausgeführt wird, wenn mit den Elementen, Gruppen oder Benutzern verknüpfte Ereignisse eintreten. ArcGIS Notebook Serverfungiert als Empfänger der Webhook-Payload. Nach dem Auslösen eines Webhooks erfolgt eine HTTP-Anforderung an ArcGIS Notebook Server zum Ausführen eines ausgewählten Notebooks, ohne dass eine Benutzerinteraktion erforderlich ist.

Hinweis:

Die Anzahl gleichzeitig ausgeführter Notebooks wird durch die Systemeigenschaft maxExecuteNotebookContainersPerNode in ArcGIS Notebook Server beschränkt.

Erstellen eines Organisations-Webhook

Webhooks können auf der Seite Organisationseinstellungen verwaltet werden. Führen Sie zum Erstellen eines Webhooks die folgenden Schritte aus:

1. Melden Sie sich als Standardadministrator oder mit einer benutzerdefinierten Rolle mit der Berechtigung für Organisations-Webhooks an.
2. Klicken Sie auf Organisation > Einstellungen > Webhooks.
3. Klicken Sie im Abschnitt "Organisations-Webhooks" auf Webhook erstellen.
4. Geben Sie einen Webhook-Namen an.
5. Wählen Sie den Typ des Ereignisses aus, das den Webhook auslöst.

   Standardmäßig werden alle Ereignistypen (Elemente, Benutzer, Gruppen und Rollen) einbezogen.

   Weitere Informationen finden Sie unter Unterstützte Trigger-Ereignisse.

6. Wählen Sie als Payload-Typ Notebook aus.

   Hinweis:

   Wenn die Option Notebook nicht verfügbar ist, wurde Notebook Server nicht für das Portal konfiguriert. Wenn die Option Notebook verfügbar ist, jedoch nicht ausgewählt werden kann, besitzen Sie keine Notebooks, für die Webhooks konfiguriert werden können. Sie müssen der Besitzer des Notebook-Elements sein, das für den Webhook verwendet werden soll.

7. Wählen Sie das Notebook aus, das beim Auslösen des Webhooks ausgeführt werden soll.
8. Geben Sie optional einen geheimen Schlüssel (Secret) an, der in die Webhook-Payload einbezogen wird.

   Sie können auch auswählen, dass für den geheimen Schlüssel (Secret) vorab generierte Zufallswerte verwendet werden.

9. Klicken Sie auf Webhook erstellen, um die Webhook-Einstellungen zu speichern und einen Webhook zu erstellen.

Verwalten von Organisations-Webhooks

Webhooks können auf der Seite Organisationseinstellungen verwaltet werden. Führen Sie zum Verwalten vorhandener Webhooks die folgenden Schritte aus:

1. Melden Sie sich als Standardadministrator oder mit einer benutzerdefinierten Rolle mit der Berechtigung für Organisations-Webhooks an.
2. Klicken Sie auf Organisation > Einstellungen > Webhooks, um eine Liste der Organisations-Webhooks anzuzeigen, die von Ihnen und anderen Webhook-Administratoren erstellt wurden.

Sie können die vorhandenen Webhooks mit den folgenden Aktionen verwalten:

• Webhook deaktivieren: Wenn ein Webhook aktiv ist, klicken Sie auf Aktiv. Durch das Deaktivieren des Webhooks werden beim Auslösen des Webhooks keine Payloads mehr übermittelt.
• Webhook aktivieren: Wenn ein Webhook deaktiviert ist, klicken Sie auf Nicht aktiv. Sobald der Webhook aktiviert ist, wird die Übermittlung von Payloads wieder aufgenommen.
• Webhook bearbeiten: Klicken Sie auf die Schaltfläche "Optionen" für den Webhook, und klicken Sie auf Bearbeiten, um den Webhook zu aktualisieren.
• Webhook löschen: Klicken Sie auf die Schaltfläche "Optionen" für den Webhook, und klicken Sie auf Löschen. Klicken Sie auf Bestätigen, um den Webhook zu löschen.

Ändern der erweiterten Organisations-Webhook-Einstellungen

Verwenden Sie "Erweiterte Webhook-Einstellungen", um Eigenschaften wie die zulässige Anzahl von Übermittlungsversuchen, Benachrichtigungen über die verstrichene Zeit und Benachrichtigungs-Timeout-Eigenschaften für Webhooks zu ändern. Diese erweiterten Einstellungen werden auf alle Webhooks Ihrer Organisation angewendet. Führen Sie zum Ändern der erweiterten Webhook-Einstellungen die folgenden Schritte aus:

1. Melden Sie sich als Standardadministrator oder mit einer benutzerdefinierten Rolle mit der Berechtigung für Organisations-Webhooks an.
2. Klicken Sie auf Organisation > Einstellungen > Webhooks.
3. Klicken Sie im Abschnitt "Organisations-Webhooks" auf Erweiterte Einstellungen, um die Standardwerte der erweiterten Webhook-Eigenschaften zu ändern.

Payload von Organisations-Webhooks

Wenn ein Notebook über einen Webhook ausgeführt wird, werden die Informationen zur Webhook-Payload automatisch in die erste Zelle des Notebooks eingefügt. Nach dem Einfügen können die in der Webhook-Payload bereitgestellten Informationen für weitere Automatisierungs-Workflows im Notebook verwendet werden.

Webhook-Payload-Information in einem Notebook:

webhookPayload = {
    "properties": {
        "itemId": "<notebook_item_id>"
    },
    "events": [
        {
            "source": "<items | user | group | role>",
            "id": "<source_id>",
            "userId": "<user_id_of_member_triggered_webhook>",
            "when": 1742596800000,
            "operation": "<operation_triggered_webhook>",
            "properties": {"<operation_details>"},
            "username": "<username_of_member_triggered_webhook>"
        }
    ],
    "info": {
        "webhookId": "<webhook_id>",
        "portalURL": "<portal_url>",
        "webhookName": "<webhook_name>",
        "when": 1742596805000
    }
}

Automatisieren eines Notebooks mithilfe von Service-Webhooks

Webhooks – z. B. für asynchrone Geoverarbeitungsservices, Feature-Services und andere generische Webhooks – können als Reaktion auf bestimmte Ereignisse eine Notebook-Ausführung auslösen. Administratoren können eine Webhook-Empfänger-URL als Hook- oder Payload-URL für diese Webhooks registrieren. Wenn ein bestimmtes mit einem Webhook verknüpftes Ereignis ausgelöst wird, wird automatisch die URL des Notebook-Webhook-Empfängers aufgerufen und die Ausführung des entsprechenden Notebooks eingeleitet.

In den folgenden Abschnitten wird die Konfiguration eines Notebook-Webhook-Empfängers in ArcGIS Notebook Server beschrieben.

Erstellen und Kopieren eines API-Schlüssels

Ein API-Schlüssel ist ein langlebiges Token, das einen Service-Webhook autorisiert, ein verknüpftes Notebook-Element auszuführen und sicher auf die Funktionen und Funktionalitäten von ArcGIS Enterprise zuzugreifen, die für die Ausführung des Notebooks erforderlich sind.

API-Schlüssel werden mithilfe von Anmeldeinformationen für API-Schlüssel generiert. Dieser Elementtyp wird in Ihrer Organisation gehostet. Anmeldeinformationen für API-Schlüssel enthalten Einstellungen, mit denen Sie API-Schlüssel generieren und Eigenschaften wie deren Berechtigungen und das Ablaufdatum verwalten können. Der Prozess zur Erstellung von Anmeldeinformationen für API-Schlüssel und Verwendung von API-Schlüsseln in Ihrer Anwendung wird als Authentifizierung per API-Schlüssel bezeichnet.

Führen Sie zum Erstellen und Kopieren eines API-Schlüssels die folgenden Schritte aus:

1. Melden Sie sich als Administrator bei Ihrem Portal an.
2. Klicken Sie auf die Seite Elementdetails des API-Schlüssel-Elements.
3. Führen Sie die Schritte im Lernprogramm Erstellen eines API-Schlüssels aus, um einen API-Schlüssel zu erstellen und zu kopieren. Gewähren Sie die Berechtigungen zum Erstellen und Bearbeiten von Notebooks, zum Erstellen, Aktualisieren und Löschen von Elementen sowie optional die Berechtigung ''Erweiterte Notebooks'' für ArcPy.

   Je nach den im Notebook durchgeführten Workflows können zusätzliche Berechtigungen erforderlich sein.

Registrieren eines Notebook-Webhook-Empfängers

Führen Sie zum Registrieren eines Notebook-Webhook-Empfängers die folgenden Schritte aus:

1. Melden Sie sich als Administrator bei Ihrem Portal an.
2. Klicken Sie auf Organisation > Einstellungen > Webhooks > Webhook-Empfänger erstellen.
3. Geben Sie einen Namen für Ihren Webhook-Empfänger ein.
4. Wählen Sie das Notebook aus, auf dem der Webhook-Empfänger ausgeführt werden soll.
5. Geben Sie einen 32-stelligen geheimen Schlüssel ein, der zur Sicherstellung der Herkunft des Webhooks verwendet wird.
6. Geben Sie eine durch Kommas getrennte Liste von Signatur-Headern ein, die auf eine verschlüsselte Payload überprüft werden sollen.
7. Geben Sie den API-Token mit Berechtigungen für den Zugriff auf das Element "Notebook", Berechtigungen zum Erstellen von Notebooks/erweiterten Notebooks und alle anderen GIS-Funktionen im Notebook ein.
8. Geben Sie optional Parameter im JSON-Format ein.
9. Klicken Sie auf Empfänger erstellen.

Erstellen eines Webhooks für einen asynchronen Geoverarbeitungsservice oder einen Feature-Service

Führen Sie die folgenden Schritte aus, um einen Webhook für einen asynchronen Geoverarbeitungsservice oder einen Feature-Service zu erstellen:

1. Verwenden Sie die URL des Webhook-Empfängers, geheime Kopfzeilen und Signatur-Header, um einen Webhook für einen Service zu erstellen.
2. Überprüfen Sie, ob das mit dem Notebook-Webhook-Empfänger verknüpfte Notebook jedes Mal ausgeführt wird, wenn ein bestimmtes Service-Webhook-Ereignis ausgelöst wird.

Payload von Service-Webhooks

Wenn ein Notebook über einen Webhook ausgeführt wird, werden die Informationen zur Webhook-Payload automatisch in die erste Zelle des Notebooks eingefügt. Nach dem Einfügen können die in der Webhook-Payload bereitgestellten Informationen für weitere Automatisierungs-Workflows im Notebook verwendet werden.

Feature-Service-Webhooks

Der folgende Code ist ein Beispiel für eine Payload für einen Feature-Service-Webhook.

webhookPayload = {
    "serviceType": "FeatureServer",
    "changesUrl": "<change_url>",
    "name": "<webhook_name>",
    "id": "<webhook_id>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "FeaturesCreated",
            "when": 1740436800000
        },
        {
            "eventType": "FeaturesDeleted",
            "when": 1740436810000
        },
        {
            "eventType": "FeaturesUpdated",
            "when": 1740436820000
        }
    ]
}

Geoverarbeitungsservice-Webhooks

Der folgende Code ist ein Beispiel für eine Payload für einen Geoverarbeitungsservice-Webhook.

webhookPayload = {
    "serviceType": "GPServer",
    "jobId": "<job_id>",
    "statusURL": "<status_url>",
    "name": "<webhook_name>",
    "taskName": "<task_name>",
    "folderName": "<folder_name>",
    "serviceName": "<service_name>",
    "events": [
        {
            "eventType": "esriJobSucceeded",
            "when": 1742337000000
        }
    ]
}