Automatizzare i flussi di lavoro con ArcGIS Notebooks

ArcGIS Notebook Server permette di implementare diversi metodi di automazione del flusso di lavoro, compresa l'automazione attraverso i notebook programmati, i webhook e i propri script personalizzati utilizzando l'API amministrativa Execute Notebook.

Nota:

Per automatizzare un notebook utilizzando attività pianificate, webhook o l'API Run Notebook, la versione del runtime del notebook deve essere 3.0 o successiva.

Programmare i compiti del notebook

A partire da 10.8.1, gli autori dei notebook possono pianificare ArcGIS Notebooks per l'esecuzione automatizzata a un'ora fissa nel futuro, una tantum o su base ricorrente. La creazione di attività per pianificare i notebook ti permette di automatizzare i flussi di lavoro di routine, eseguire processi ad alta intensità di dati durante le ore non di punta e aggiornare regolarmente i set di dati. Ad esempio, si possono pianificare gli appunti per realizzare quanto segue:

• Importare dati da una fonte online che si aggiorna mensilmente, resettare automaticamente i dati e applicare trasformazioni necessarie e spostare i dati sul workspace.
• Eseguire un flusso di lavoro di analisi big data che richiede un'elevata potenza di elaborazione durante la notte, quando le risorse della macchina sono inutilizzate.
• Gestire gli utenti che hanno creato account nel portale nella settimana precedente e inviare l'elenco a se stessi in un'e-mail.

Puoi creare uno o più compiti per un notebook. Per impostazione predefinita, l'autore del notebook o l'amministratore è in grado di creare un massimo di 20 attività. Se la proprietà del notebook viene cambiata, tutti i compiti associati a quel notebook saranno disattivati e assegnati al nuovo proprietario.

I compiti programmati permettono di parametrizzare i notebook. Quando un notebook è parametrizzato, permette di scrivere codice generico che può essere adattato a input variabili senza la tua interazione. I parametri scelti sono inseriti nel notebook quando si esegue un'attività e, opzionalmente, possono essere salvati nel notebook. Per esempio, un notebook parametrizzato può essere usato per generare rapporti sull'inquinamento atmosferico a livello regionale su base ricorrente. Il notebook può avere più compiti programmati, uno per ogni regione da studiare, e per ogni compito, gli input parametrizzati come il nome della città e il tipo di inquinamento possono essere inseriti nel notebook.

Nota:

Il numero di attività del notebook in esecuzione simultanea è limitato dalla proprietà di sistema maxExecuteNotebookContainersPerNode in Notebook Server.

È possibile configurare l'attività per salvare lo stato del notebook nell'elemento originale del notebook dopo il completamento.

Una vista HTML statica del notebook sarà salvata per ogni attività pianificata che viene eseguita.

Usando la finestra Gestisci attività della home page di ArcGIS Notebook Server o la pagina Attività in ArcGIS Notebook Server Manager, gli amministratori possono visualizzare i dettagli, modificare, sospendere e riprendere o eliminare ciascuna attività di notebook attiva nel sito. Gli amministratori e gli autori di notebook con il privilegio di pianificare notebook possono visualizzare i dettagli, modificare, mettere in pausa e riprendere o eliminare un'attività del notebook nella pagina dei dettagli del notebook o nel riquadro delle attività dell'editor del notebook.

Se una precedente esecuzione di un'attività è ancora in corso, l'esecuzione di una nuova attività programmata verrà saltata. Per esempio, se un compito è programmato per essere eseguito ogni 15 minuti, ma un'istanza di quel compito viene eseguita per 20 minuti, la prossima esecuzione programmata sarà saltata. Se questo accade regolarmente, il proprietario del compito dovrebbe regolare l'intervallo di tempo programmato in modo che non ci sia sovrapposizione tra le esecuzioni.

Per maggiori informazioni sulle attività pianificate del notebook, vedi l'argomento della guida Pianificazione di un'attività del notebook.

Limite attività pianificate

Esistono determinati limiti del livello utente, organizzazione e sito ArcGIS Notebook Server (macchina) correlati alle attività di notebook pianificate.

Modificare il numero massimo di esecuzioni simultanee di notebook automatizzate (maxExecuteNotebookContainersPerNode)

Quando un notebook viene eseguito da un'attività pianificata, un webhook o dall'API Execute Notebook, ArcGIS Notebook Server apre automaticamente un nuovo contenitore ed esegue il notebook senza interazione dell'utente. Per impostazione predefinita, ArcGIS Notebook Server è configurato per eseguire un massimo di 10 esecuzioni simultanee di notebook per ogni computer Notebook Server. Considerando le risorse (CPU e RAM) disponibili su ogni computer nel sito Notebook Server, un amministratore può regolare questo limite modificando la proprietà di sistema maxExecuteNotebookContainersPerNode in Notebook Server. Ogni richiesta del notebook automatizzata inoltrata dopo il superamento di questo limite verrà aggiunta a una coda ed eseguita quando il numero di esecuzioni dell'attività automatizzata scende sotto questo limite. Le attività in coda non riusciranno se il tempo di attesa è superiore alla durata del timeout.

Nota:

Ciò non limita il numero di notebook in esecuzione interattiva dall'editor di notebook.

Puoi modificare il limite maxExecuteNotebookContainersPerNode con la procedura seguente.

Nota:

L'incremento del limite può causare l'uso di risorse aggiuntive in computer Notebook Server.

1. Effettuare l'accesso al portale ArcGIS Enterprise come amministratore.
2. Apri ArcGIS Notebook Server Manager.
3. Fai clic su Impostazioni > Sito
4. Modifica il valore della proprietà maxExecuteNotebookContainersPerNode.
5. Fare clic su Salva.
6. Esamina l'avvertenza relativa al riavvio di Notebook Server e fai clic su Salva e riavvia per salvare le modifiche.

Numero massimo di attività di notebook pianificate attive per utente

L'autore di ogni notebook con i privilegi di pianificazione notebook può creare fino a 20 attività di notebook attive. Una volta raggiunto questo limite, l'utente non può creare nuove attività pianificate. Una nuova attività può essere creata dopo che un'attività esistente passa da Attiva a Completa, Non riuscita o Inattiva. Questo limite può essere modificato aggiornando la proprietà ExecuteNotebooksUserLimit utilizzando l'operazione Aggiorna limiti di sistema nell'API ArcGIS Portal Administrator.

Numero massimo di attività dii notebook attive pianificate per organizzazione

Il numero massimo di attività di notebook attive pianificate per un'organizzazione è limitato a 200. Questo limite rappresenta il numero totale di attività attive che possono appartenere a tutti gli utenti in un'organizzazione Portal. Una volta raggiunto questo limite, gli utenti non possono creare nuove attività di notebook pianificate. Questo limite può essere modificato aggiornando la proprietà ExecuteNotebooksOrgLimit utilizzando l'operazione Aggiorna limiti di sistema nell'API ArcGIS Portal Administrator.

Numero di risultati riportati per un'attività pianificata

I risultati di un'attività sono riportati e conservati per 30 esecuzioni. Tutte le esecuzioni dell'attività precedenti alle 30 esecuzioni più recenti di un'attività vengono eliminate definitivamente. Questo limite può essere modificato aggiornando la proprietà TaskRunHistoryCount utilizzando l'operazione Aggiorna limiti di sistema nell'API ArcGIS Portal Administrator.

Errore automatico di un'attività

Tutte le attività che non riescono per cinque volte consecutive verranno commutate automaticamente in stato Non riuscito e non verranno più eseguite. Il proprietario del compito deve assicurarsi che il notebook possa essere eseguito con successo senza alcuna interazione dell'utente prima di riattivare il compito. Per accertarsi che l'esecuzione delle attività continui, il proprietario dell'attività deve identificare e correggere l'errore e modificare lo stato dell'attività in Attivo. Questo limite può essere modificato aggiornando la proprietà FailedRunsDisableTask utilizzando l'operazione Aggiorna limiti di sistema nell'API ArcGIS Portal Administrator.

Automatizzare un notebook usando i webhook dell'organizzazione

Un webhook è un meccanismo che consente a un'applicazione di fornire ad altre applicazioni informazioni determinate da eventi. Come amministratore o utente di ArcGIS Enterprise Portal con il privilegio Webhook organizzazione puoi creare, gestire e configurare webhook. Puoi configurare webhook per l'esecuzione automatica di un notebook di proprietà quando si verificano eventi associati a elementi, gruppi o utenti del tuo portale. Notebook Server funge da ricevitore del payload del webhook. Una volta che un webhook è attivato, una richiesta HTTP viene fatta al Notebook Server per eseguire un notebook scelto senza alcuna interazione dell'utente.

Nota:

Il numero di esecuzioni simultanee di notebook da parte di webhook è limitato dalla proprietà di sistema maxExecuteNotebookContainersPerNode in Notebook Server.

Creare un webhook

I webhook possono essere gestiti dalla pagina Impostazioni organizzazione del portale. Attenersi alla seguente procedura per creare un webhook:

1. Accedi come amministratore predefinito con un ruolo personalizzato con il privilegio webhook organizzazione.
2. Accedi a Organizzazione > Impostazioni > Webhook.
3. Fare clic su Crea webhook.
4. Specifica un nome del webhook.

   Ad esempio, è possibile digitare Name=mynotebook_webhook.

5. Seleziona il tipo di evento che attiverà il webhook.

   Per impostazione predefinita, sono considerati tutti i tipi di eventi (elementi, utenti, gruppi e ruoli).

6. Utilizza Attivatore per accettare il valore predefinito (/) o specifica uno o più valori come eventi di attivazione.

   Un esempio è Evento=/elementi, /elementi/<itemId>,/utenti.

   Per ulteriori informazioni, consulta Eventi di attivazione supportati.

   Per ulteriori esempi, consulta Eventi di attivazione.

7. Seleziona Notebook come tipo di payload.

   Nota:

   Se l'opzione Notebook non è disponibile, Notebook Server non è stato configurato con il tuo portale. Se l'opzione Notebook è disponibile ma non può essere selezionata, non possiedi alcun notebook disponibile per la configurazione di webhook. Devi possedere un elemento notebook che verrà utilizzato per il webhook.

8. Seleziona il notebook che verrà eseguito quando verrà attivato il webhook.
9. Facoltativamente, inserisci la chiave di un Segreto che verrà inclusa nel payload del webhook.

   Per la chiave del Segreto puoi scegliere di utilizzare anche valori casuali generati precedentemente.

10. Fare clic su Crea webhook per salvare le impostazioni del webhook e creare un webhook.

Gestire webhook

I webhook possono essere gestiti dalla pagina Impostazioni organizzazione del portale. Completare questa procedura per gestire i webhook esistenti:

1. Accedere come amministratore predefinito o come ruolo personalizzati con il privilegio di webhook organizzazione.
2. Passa a Organizzazione > Impostazioni > Webhook per visualizzare un elenco di webhook creati personalmente e da altri amministratori di webhook.

È possibile gestire i webhook esistenti con le seguenti operazioni.

• Disattiva - Quando un webhook è in stato attivo, fare clic su Attivo. Sarà richiesto di confermare la modifica dello stato. Fare clic su Conferma per disattivare il webhook. La disattivazione del webhook interrompe la consegna dei payload quando viene attivato il webhook.
• Attiva webhook - Quando un a webhook è in stato inattivo, fare clic su Inattivo. Sarà richiesto di confermare la modifica dello stato. Fare clic su Conferma per attivare il webhook. Quando il webhook viene attivato, riprende la consegna dei payload.
• Modifica webhook - Fare clic sul pulsante delle opzioni sul webhook e fare clic su Modifica per aggiornare gli eventi trigger del webhook o il notebook specificato per il webhook.
• Elimina webhook - Fare clic sul pulsante delle opzioni sul webhook e fare clic su Elimina. Fare clic su Conferma per eliminare il webhook.

Impostazioni avanzate webhook

Utilizzare le impostazioni di Webhook avanzato per modificare le proprietà quali il numero di tentativi di consegna che è possibile effettuare, le notifiche per il tempo trascorso e il timeout di notifica per i webhook. Tali impostazioni avanzate si applicano a tutti i webhook del portale. Per modificare le impostazioni di webhook Avanzate, attenersi alla procedura seguente:

1. Accedere come amministratore predefinito o come ruolo personalizzati con il privilegio di webhook organizzazione.
2. Accedi a Organizzazione > Impostazioni > Webhook > Impostazioni avanzate webhook per modificare i valori predefiniti delle proprietà avanzate del webhook.

Webhook payload

Quando un notebook viene eseguito da parte di un webhook, le informazioni del payload del webhook vengono inserite automaticamente nel notebook in una cella iniziale. Una volta iniettate, le informazioni fornite nel payload del webhook possono essere utilizzate nel notebook per ulteriori flussi di lavoro di automazione.

Informazioni sul payload del webhook incluse in un 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\>,
  }
}

Automatizzare un notebook usando i webhook

Introdotta come feature beta in ArcGIS Notebook Server 11.4, i webhook, compresi quelli per i servizi di geoprocessing asincrono, i feature service e altri webhook generici, possono attivare l'esecuzione di un notebook in risposta a specifici eventi. Gli amministratori possono registrare un URL ricevitore webhook come URL hook o di payload per tali webhook. Quando si attiva un evento specifico, associato con un webhook, chiamerà automaticamente l'URL ricevitore webhook notebook, avviando l'esecuzione del notebook corrispondente.

Le sezioni che seguono descrivono come configurare un ricevitore webhook di notebook in ArcGIS Notebook Server.

Creare un'applicazione chiave API

Una chiave API è un token di lunga durata che autorizza un webhook di servizio a eseguire un elemento del notebook associato e ad accedere in modo sicuro alle funzionalità di ArcGIS Enterprise richieste per l'esecuzione del notebook.

Le chiavi API sono generate utilizzando le credenziali della chiave API, un tipo di elemento ospitato nel tuo portale. Le credenziali della chiave API contengono impostazioni che consentono di generare chiavi API e gestire alcune proprietà, quali i relativi privilegi e la data di scadenza. Il processo di creazione delle credenziali della chiave API e l'utilizzo di chiavi API nella propria applicazione è noto come autenticazione di chiave API.

Vedere il tutorial Creare una chiave API per conoscere i passaggi per la generazione di una chiave API.

Nota:

Prima di effettuare il passaggio finale di copia della cache, effettuare i passaggi delle sezioni che seguono per applicare i privilegi aggiuntivi, necessari per l'esecuzione del notebook.

Applicare i privilegi all'applicazione chiave API.

Per applicare i privilegi aggiuntivi all'applicazione chiave API, procedere come segue:

1. Accedere alla directory di Portal utilizzando le credenziali dell'utente amministrativo utilizzate per creare la chiave API.

   L'URL per la directory di Portal è https://portal.domain.com/webadaptorname/sharing/rest.

   Dopo l'accesso, sarai reindirizzato alla pagina delle Risorse utente per l'utente che ha effettuato l'accesso.

   L'URL della pagina delle Risorse utente è https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>

2. Fare clic su Contenuti utente.
3. Fare clic sul link dell'elemento corrispondente alla chiave API creata di recente.

   Si apre la pagina API dei dettagli dell'elemento per la chiave API: https://portal.domain.com/webadaptorname/sharing/rest/community/users/<username>/items/<itemId>

4. Fare clic su Aggiorna app
5. Accodare i seguenti privilegi nella sezione Privilegi.
   1. Concedere l'autorizzazione all'esecuzione di un notebook: "premium:publisher:createNotebooks"
   2. In alternativa, consentire l'importazione e l'utilizzo di ArcPy nel notebook associato: "premium:publisher:createAdvancedNotebooks"
   3. Aggiungere eventuali altri privilegi necessari per l'esecuzione corretta del codice del notebook.

   L'esempio di chiave API che segue offre il privilegio di accedere all'elemento del notebook referenziato dal suo itemId, i privilegi per notebook standard e avanzati e i privilegi per pubblicare i feature layer.

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

6. Fare clic su Aggiorna app per salvare le modifiche.
7. Uscire dalla directory diPortal.

Generare e copiare una chiave API

Completare la procedura seguente per generare e copiare una chiave API:

1. Accedere al portale come un utente amministrativo.
2. Fare clic sulla pagina Dettagli elemento dell'elemento della chiave API.
3. Procedere nel modo descritto nella sezione Copiare la chiave API del tutorial Creare una API.

Registrare un ricevitore webhook del notebook

Per registrare un ricevitore webhook del notebook, precedere nel seguente modo:

1. Accedere alla directory Administrator di ArcGIS Notebook Server utilizzando le credenziali dell'utente amministrativo del portale.

   L'URL è https://notebookserverwebadaptor.domain.com/webadaptor/admin.

2. Fare clic su Notebook > Ricevitori webhook > Registra ricevitore webhook.

   L'URL è https://notebookserverwebadaptor.domain.com/webadaptor/admin/notebooks/webhookReceivers/create.

3. Registrare il ricevitore webhook utilizzando le informazioni riportate all'argomento Creare ricevitore webhook nell'API amministrativa

   Dopo aver creato con successo un ricevitore webhook notebook, nella risposta verrà restituito un URL del ricevitore webhook. L'URL è utilizzabile come URL hook quando si registrano webhook di servizio di geoprocessing asincrono, webhook di feature service e altre webhook generici.

Creare un webhook di servizio di geoprocessing asincrono o di feature service

Per creare un webhook di servizio di geoprocessing asincrono o di feature service, procedere nel seguente modo:

1. Utilizzare l'URL del ricevitore webhook, le intestazioni segrete e le intestazioni della firma per creare un webhook di servizio asincrono.
2. Confermare che il notebook associato con il ricevitore webhook del notebook effettua l'esecuzione ogni volta che è attivato un evento webhook di servizio specifico.

API Execute Notebook

Gli amministratori e gli autori di notebook possono anche automatizzare l'esecuzione di un notebook senza l'interazione dell'utente utilizzando l'operazione Esegui notebook nella directory dell'amministratore di ArcGIS Notebook Server. Questa operazione eseguirà automaticamente un notebook quando viene chiamata, ma utilizzando un tuo script personalizzato puoi pianificarlo per un'esecuzione automatica a un orario impostato o in base a una pianificazione regolare. Un cron job o uno scheduler di Windows può anche essere usato per programmare l'operazione Execute Notebook per essere eseguita ad un'ora stabilita o ad un intervallo ricorrente.

Per ulteriori informazioni, consultare l'argomento Execute Notebook nella guida di riferimento della Administrator Directory.