Automatisieren von Workflows mit ArcGIS Notebooks

Mit ArcGIS Notebook Server können Sie mehrere Methoden der Workflow-Automatisierung implementieren, einschließlich der Automatisierung durch geplante Notebooks, durch Webhooks und durch eigene benutzerdefinierte Skripte mithilfe der Verwaltungs-API "Notebook ausführen".

Hinweis:

Zum Automatisieren eines Notebooks mithilfe von geplanten Tasks, Webhooks oder der API "Notebook ausführen" muss das Notebook mit einer Runtime der Version 3.0 oder höher ausgeführt werden.

Erstellen eines Zeitplans für Notebook-Tasks

Ab Version 10.8.1 können Notebook-Autoren die automatische Ausführung von ArcGIS Notebookszu einem festen Zeitpunkt in der Zukunft planen, entweder einmalig oder in regelmäßigen Abständen. Die Erstellung von Tasks zur Planung von Notebooks ermöglicht die Automatisierung von Routineaufgaben, die Ausführung von datenintensiven Prozessen in Zeiten mit geringer Auslastung sowie die regelmäßige Aktualisierung von Datasets. Sie können für ein Notebook z. B. folgende Aufgaben planen:

• Importieren von Daten aus einer Online-Quelle, die monatlich aktualisiert wird, automatisches Bereinigen der Daten und Anwenden erforderlicher Transformationen sowie Verschieben der Daten in Ihren Workspace.
• Ausführen eines Workflows zur Big-Data-Analyse, der hohe Rechenleistung erfordert, über Nacht, wenn die Computerressourcen nicht anderweitig genutzt werden.
• Verwalten von Benutzern, die während der letzten Woche Konten im Portal erstellt haben, und Senden der Liste per E-Mail an Ihre Adresse

Sie können einen oder mehrere Tasks für ein Notebook ausführen. Standardmäßig kann der Notebook-Autor oder Administrator maximal 20 Tasks erstellen. Wenn ein Notebook den Besitzer wechselt, werden alle mit dem Notebook verknüpften Tasks deaktiviert und dem neuen Besitzer zugewiesen.

Mit geplanten Tasks können Sie Notebooks parametrisieren. Ein parametrisiertes Notebook ermöglicht Ihnen das Schreiben von generischem Code, der ohne Ihre Interaktion an variierende Eingaben angepasst werden kann. Die ausgewählten Parameter werden in das Notebook eingefügt, wenn ein Task ausgeführt wird, und können optional im Notebook gespeichert werden. Beispielsweise können mit einem parametrisierten Notebook regelmäßig Berichte zur Luftverschmutzung für eine gesamte Region generiert werden. Das Notebook kann mehrere geplante Tasks, einer pro zu untersuchender Region, aufweisen, und für jeden Task können parametrisierte Eingaben, z. B. Ortsname und Verschmutzungstyp, in das Notebook eingespeist werden.

Hinweis:

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

Sie können den Task so konfigurieren, dass der Zustand des Notebooks nach Abschluss des Tasks im ursprünglichen Notebook-Element gespeichert wird.

Für jeden ausgeführten geplanten Task wird eine statische HTML-Ansicht des Notebooks gespeichert.

Mithilfe des Fensters Tasks verwalten auf der ArcGIS Notebook Server-Startseite oder der Seite Tasks in ArcGIS Notebook Server Manager können Administratoren Detailinformationen zu den einzelnen aktiven Notebook-Tasks in der Site anzeigen und die Tasks bearbeiten, anhalten und fortsetzen oder löschen. Administratoren und Notebook-Autoren mit der Berechtigung "Zeitplan für Notebooks festlegen" können auf der Detailseite des Notebooks oder im Task-Bereich des Notebook-Editors Detailinformationen zu einem Notebook-Task anzeigen und den Task bearbeiten, anhalten/fortsetzen oder löschen.

Ein neuer geplanter Task wird übersprungen, wenn eine vorherige Ausführung des Tasks noch nicht abgeschlossen ist. Wenn z. B. für einen Task geplant ist, dass er alle 15 Minuten ausgeführt wird, das Ausführen einer Instanz des Tasks jedoch 20 Minuten dauert, wird die nächste geplante Ausführung übersprungen. Falls dies regelmäßig eintritt, sollte der Task-Besitzer das geplante Zeitintervall so anpassen, dass sich keine Ausführungen überlappen.

Weitere Informationen zu geplanten Notebook-Tasks finden Sie im Hilfethema Erstellen eines Zeitplans für Notebook-Tasks.

Beschränkungen für geplante Tasks

Für geplante Notebook-Tasks sind bestimmte Beschränkungen auf Benutzer-, Organisations- und ArcGIS Notebook Server-Site- (Computer-)Ebene vorhanden.

Ändern der maximalen Anzahl gleichzeitiger automatisierter Notebook-Ausführungen (maxExecuteNotebookContainersPerNode)

Beim Ausführen eines Notebooks durch einen geplanten Task, einen Webhook oder die API "Notebook ausführen" wird von ArcGIS Notebook Server automatisch ein neuer Container geöffnet und das Notebook ohne Benutzerinteraktion ausgeführt. Standardmäßig erfolgen durch ArcGIS Notebook Server maximal 10 gleichzeitige Notebook-Ausführungen pro Notebook Server-Computer. Ein Administrator kann unter Berücksichtigung der auf jedem Computer in der Notebook Server-Site verfügbaren Ressourcen (CPU und Arbeitsspeicher) diese Beschränkung durch Ändern der Systemeigenschaft maxExecuteNotebookContainersPerNode in Notebook Server anpassen. Anforderungen automatisierter Notebooks, die nach Überschreitung dieser Beschränkung gesendet werden, werden einer Warteschlange hinzugefügt und ausgeführt, sobald die Anzahl der automatisierten Task-Ausführungen unter die Beschränkung fällt. Tasks, die sich in der Warteschlange befinden, schlagen fehl, wenn die Wartezeit die Timeout-Zeit überschreitet.

Hinweis:

Die Anzahl der interaktiv über den Notebook-Editor ausgeführten Notebooks wird dadurch nicht eingeschränkt.

Sie können die Beschränkung maxExecuteNotebookContainersPerNode mit den folgenden Schritten ändern.

Hinweis:

Das Heraufsetzen des Limits für die Beschränkung kann zu einem zusätzlichen Ressourcenverbrauch beim Notebook Server-Computer führen.

1. Melden Sie sich als Administrator bei Ihrem ArcGIS Enterprise-Portal an.
2. Öffnen Sie ArcGIS Notebook Server Manager.
3. Klicken Sie auf Einstellungen > Site.
4. Ändern Sie den Wert für die Eigenschaft maxExecuteNotebookContainersPerNode.
5. Klicken Sie auf Speichern.
6. Lesen Sie die Warnung zum Neustarten von Notebook Server, und klicken Sie auf Speichern und neu starten, um die Änderungen zu speichern.

Maximale Anzahl aktiver geplanter Notebook-Tasks pro Benutzer

Jeder Notebook-Autor mit der Berechtigung "Zeitplan für Notebooks festlegen" kann bis zu 20 aktive Notebook-Tasks erstellen. Sobald dieses Limit erreicht ist, kann der Benutzer keine neuen geplanten Tasks mehr erstellen. Ein neuer Task kann erstellt werden, wenn sich der Status eines vorhandenen Tasks von "Aktiv" zu "Abgeschlossen", "Nicht erfolgreich" oder "Inaktiv" ändert. Diese Beschränkung kann durch Aktualisierung der Eigenschaft ExecuteNotebooksUserLimit mithilfe des Vorgangs zum Aktualisieren von Systembeschränkungen in der ArcGIS Portal Administrator API geändert werden.

Maximale Anzahl aktiver geplanter Notebook-Tasks pro Organisation

Die maximale Anzahl aktiver geplanter Notebook-Tasks für eine Organisation ist auf 200 beschränkt. Dies ist die Gesamtzahl aktiver Tasks aller Benutzer in einer Portal-Organisation. Sobald dieses Limit erreicht ist, können Benutzer keine neuen geplanten Notebook-Tasks mehr erstellen. Diese Beschränkung kann durch Aktualisierung der Eigenschaft ExecuteNotebooksOrgLimit mithilfe des Vorgangs zum Aktualisieren von Systembeschränkungen in der ArcGIS Portal Administrator API geändert werden.

Anzahl der berichteten Ergebnisse für einen geplanten Task

Die Ergebnisberichte der letzten 30 Ausführungen eines Tasks werden gespeichert. Die Ergebnisse früherer Ausführungen des Tasks werden dauerhaft gelöscht. Diese Beschränkung kann durch Aktualisierung der Eigenschaft TaskRunHistoryCount mithilfe des Vorgangs zum Aktualisieren von Systembeschränkungen in der ArcGIS Portal Administrator API geändert werden.

Automatischer Task-Fehler

Tasks, die fünfmal aufeinanderfolgend fehlschlagen, werden automatisch in den Status "Nicht erfolgreich" versetzt und nicht mehr ausgeführt. Der Task-Besitzer muss vor dem Reaktivieren des Tasks sicherstellen, dass das Notebook ohne Benutzerinteraktion erfolgreich ausgeführt werden kann. Um sicherzustellen, dass die Tasks weiterhin ausgeführt werden, muss der Task-Besitzer den Fehler identifizieren und beheben sowie den Task in den Status "Aktiv" versetzen. Diese Beschränkung kann durch Aktualisierung der Eigenschaft FailedRunsDisableTask mithilfe des Vorgangs zum Aktualisieren von Systembeschränkungen in der ArcGIS Portal Administrator API geändert werden.

Automatisieren eines Notebooks mithilfe von Organisations-Webhooks

Ein Webhook ist ein Mechanismus, der es einer Anwendung ermöglicht, für andere Anwendungen ereignisgesteuerte Informationen bereitzustellen. Als ArcGIS Enterprise-Portal-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 Portal-Elementen, -Gruppen oder -Benutzern verknüpfte Ereignisse eintreten. Notebook Server fungiert als Empfänger der Webhook-Payload. Nach dem Auslösen eines Webhooks erfolgt eine HTTP-Anforderung an 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 Notebook Server beschränkt.

Erstellen eines Webhooks

Webhooks können auf der Seite Organisationseinstellungen des Portals 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. Navigieren Sie zu Organisation > Einstellungen > Webhooks.
3. Klicken Sie auf Webhook erstellen.
4. Geben Sie einen Webhook-Namen an.

   Zum Beispiel können Sie folgende Eingabe vornehmen: Name=mynotebook_webhook.

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.

6. Verwenden Sie Trigger, um den Standardwert (/) zu übernehmen oder einen oder mehrere Werte als Trigger-Ereignisse festzulegen.

   Beispiel: Ereignisse=/items, /items/<itemId>,/users.

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

   Weitere Beispiele finden Sie unter Trigger-Ereignisse.

7. 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.

8. Wählen Sie das Notebook aus, das beim Auslösen des Webhooks ausgeführt werden soll.
9. 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.

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

Verwalten von Webhooks

Webhooks können auf der Seite Organisationseinstellungen des Portals 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. Navigieren Sie zu Organisation > Einstellungen > Webhooks, um eine Liste der 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. Sie werden aufgefordert, die Statusänderung zu bestätigen. Klicken Sie auf Bestätigen, um den Webhook zu deaktivieren. 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. Sie werden aufgefordert, die Statusänderung zu bestätigen. Klicken Sie auf Bestätigen, um den Webhook zu aktivieren. 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 die Trigger-Ereignisse des Webhooks oder das für den Webhook angegebene Notebook 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.

Erweiterte 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 Portal-Webhooks 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. Navigieren Sie zu Organisation > Einstellungen > Webhooks > Erweiterte Webhook-Einstellungen, um die Standardwerte der erweiterten Webhook-Einstellungen zu ändern.

Webhook-Payload

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:

{
  "properties": {
    "itemId": "<itemId of the current notebook>"
  },
  "events": [
    {
      "source": "items",
      "id": "<itemId of the item that resulted in webhook trigger>",
      "userId": "<webhook user>",
      "when": \<epoch time in ms when webhook was triggered\>,
      "operation": "<type of operation that resulted in webhook trigger>",
      "properties": {},
      "username": "<webhook username>"
    }
  ],
  "info": {
    "webhookId": "<webhookId>",
    "portalURL": "<public portal url>",
    "webhookName": "<webhook name>",
    "when": \<epoch time in ms when webhook was triggered\>,
  }
}

Automatisieren eines Notebooks mithilfe von Service-Webhooks

Die in ArcGIS Notebook Server 11.4 als Beta-Funktion eingeführten 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 einer API-Schlüssel-Anwendung

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 Ihrem Portal 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.

Die Schritte zum Generieren eines API-Schlüssels finden Sie im Lernprogramm Erstellen eines API-Schlüssels.

Hinweis:

Bevor Sie den letzten Schritt zum Kopieren des Cache durchführen, befolgen Sie die Schritte in den folgenden Abschnitten, um zusätzliche Berechtigungen anzuwenden, die zum Ausführen des Notebooks erforderlich sind.

Anwenden von Berechtigungen auf die API-Schlüssel-Anwendung

Führen Sie die folgenden Schritte aus, um zusätzliche Berechtigungen auf die API-Schlüssel-Anwendung anzuwenden:

1. Melden Sie sich beim Portal-Verzeichnis mit den Administrator-Anmeldeinformationen an, die zum Erstellen des API-Schlüssels verwendet wurden.

   Die URL für das Portal-Verzeichnis lautet https://portal.domain.com/webadaptorname/sharing/rest.

   Nachdem Sie sich angemeldet haben, wird die Seite User resource für den angemeldeten Benutzer angezeigt.

   URL der Seite User resource: https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>

2. Klicken Sie auf User Content.
3. Klicken Sie auf den Link des Elements, das dem neu erstellten API-Schlüssel entspricht.

   Die Elementdetailseite der API für den API-Schlüssel wird geöffnet: https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>/items/<itemId>

4. Klicken Sie auf Update App.
5. Hängen Sie im Abschnitt Privileges die folgenden Berechtigungen an.
   1. Gewähren Sie die Berechtigung zum Ausführen eines Notebooks: "premium:publisher:createNotebooks"
   2. Lassen Sie optional das Importieren und Verwenden von ArcPy in dem verknüpften Notebook zu: "premium:publisher:createAdvancedNotebooks"
   3. Fügen Sie andere erforderliche Berechtigungen ein, damit der Notebook-Code erfolgreich ausgeführt werden kann.

   Das folgende Beispiel für einen API-Schlüssel enthält die Berechtigung für den Zugriff auf das Notebook-Element, das über die itemId referenziert wird, über Berechtigungen für Standard- und erweiterte Notebooks sowie über Berechtigungen zum Veröffentlichen von Feature-Layern.

   [
     "portal:app:access:item:bfebec55911a4cd2a85ff9eae51dcf68",
     "premium:publisher:createAdvancedNotebooks",
     "premium:publisher:createNotebooks",
     "portal:user:createItem",
     "portal:publisher:publishFeatures"
   ]

6. Klicken Sie auf Update App, um die Änderungen zu speichern.
7. Melden Sie sich vom Portal-Verzeichnis ab.

Generieren und Kopieren eines API-Schlüssels

Führen Sie die folgenden Schritte aus, um einen API-Schlüssel zu generieren und zu kopieren:

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 Abschnitt Copy the API key des Lernprogramms "Create an API key" aus.

Registrieren eines Notebook-Webhook-Empfängers

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

1. Melden Sie sich mit den Administrator-Anmeldeinformationen des Portals beim ArcGIS Notebook Server-Administratorverzeichnis an.

   Die URL lautet https://notebookserverwebadaptor.domain.com/webadaptor/admin.

2. Klicken Sie auf Notebooks > Webhook Receivers > Register Webhook Receiver.

   Die URL lautet https://notebookserverwebadaptor.domain.com/webadaptor/admin/notebooks/webhookReceivers/create.

3. Registrieren Sie den Webhook-Empfänger mithilfe der Informationen im Thema Webhook-Empfänger erstellen in der Administrative API.

   Nach der erfolgreichen Erstellung eines Notebook-Webhook-Empfängers wird in der Antwort eine Webhook-Empfänger-URL zurückgegeben. Diese URL kann als Hook-URL bei der Registrierung von asynchronen Geoverarbeitungsservice-Webhooks, Feature-Service-Webhooks und anderen generischen Webhooks verwendet werden.

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 asynchronen 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.

API "Notebook ausführen"

Administratoren und Notebook-Autoren können ein Notebook auch mit dem Vorgang "Notebook ausführen" im ArcGIS Notebook Server-Administratorverzeichnis automatisieren, sodass es ohne Benutzerinteraktion ausgeführt wird. Durch das Aufrufen dieses Vorgangs wird ein Notebook automatisch ausgeführt. Sie können jedoch mithilfe eines eigenen benutzerdefinierten Skriptes die automatisierte Ausführung zu einem festgelegten Zeitpunkt oder in regelmäßigen Abständen planen. Zum Planen der Ausführung des Vorgangs "Notebook ausführen" zu einem festgelegten Zeitpunkt oder in regelmäßigen Abständen kann auch ein Cron-Job oder ein Windows-Taskplaner verwendet werden.

Weitere Informationen finden Sie in dem Thema zum Vorgang Execute Notebook im Administrator Directory Reference Guide.