Un webhook è un meccanismo che consente a un'applicazione di fornire ad altre applicazioni informazioni determinate da eventi. I webhook possono essere configurati a livello di organizzazione e di servizio per eseguire automaticamente un notebook quando si verificano degli eventi associati all'organizzazione o a servizi.
Automatizzare un notebook usando i webhook dell'organizzazione
Come amministratore o utente di ArcGIS Enterprise con il privilegio Webhook organizzazione è possibile creare, gestire e configurare webhook. È possibile configurare webhook per l'esecuzione automatica di un notebook di proprietà quando si verificano eventi associati a elementi, gruppi o utenti. ArcGIS Notebook Server funge da ricevitore del payload del webhook. Una volta che un webhook è attivato, una richiesta HTTP viene fatta a ArcGIS 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 ArcGIS Notebook Server.
Creare un webhook dell'organizzazione
I webhook possono essere gestiti dalla pagina Impostazioni organizzazione. Attenersi alla seguente procedura per creare un webhook:
- Accedi come amministratore predefinito con un ruolo personalizzato con il privilegio webhook organizzazione.
- Fare clic su Organizzazione > Impostazioni > Webhook.
- Nella sezione webhook dell'organizzazione, fare clic su Crea webhook.
- Specifica un nome del webhook.
- Seleziona il tipo di evento che attiverà il webhook.
Per impostazione predefinita, sono considerati tutti i tipi di eventi (elementi, utenti, gruppi e ruoli).
Per ulteriori informazioni, consulta Eventi di attivazione supportati.
- 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. - Seleziona il notebook che verrà eseguito quando verrà attivato il webhook.
- 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.
- Fare clic su Crea webhook per salvare le impostazioni del webhook e creare un webhook.
Gestire i webhook dell'organizzazione
I webhook possono essere gestiti dalla pagina Impostazioni organizzazione. Completare questa procedura per gestire i webhook esistenti:
- Accedere come amministratore predefinito o come ruolo personalizzati con il privilegio di webhook organizzazione.
- Fare clic su Organizzazione > Impostazioni > Webhook per visualizzare un elenco di webhook dell'organizzazione 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. 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. 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.
- Elimina webhook - Fare clic sul pulsante delle opzioni sul webhook e fare clic su Elimina. Fare clic su Conferma per eliminare il webhook.
Modificare le impostazioni avanzate dei webhook dell'organizzazione
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. Queste impostazioni avanzate si applicheranno a tutti i webhook dell'organizzazione. Per modificare le impostazioni di webhook Avanzate, attenersi alla procedura seguente:
- Accedere come amministratore predefinito o come ruolo personalizzati con il privilegio di webhook organizzazione.
- Fare clic su Organizzazione > Impostazioni > Webhook.
- Nella sezione dei webhook dell'organizzazione, fare clic su Impostazioni avanzate per modificare i valori predefiniti delle proprietà webhook avanzate.
Payload dei webhook dell'organizzazione
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:
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
}
}
Automatizzare un notebook usando i webhook
I webhook, compresi quelli per i servizi di geoprocessing asincroni, 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 e copiare una 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 nell'organizzazione. 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.
Per creare e copiare una chiave API, completare i seguenti passaggi:
- Accedere al portale come un utente amministrativo.
- Fare clic sulla pagina Dettagli elemento dell'elemento della chiave API.
- Seguire i passaggi nel tutorial Creare una chiave API per istruzioni su come creare e copiare una chiave API. Concedere i privilegi per creare e modificare notebook, creare, aggiornare ed eliminare elementi e, facoltativamente, concedere il privilegio di notebook avanzato per ArcPy.
Ulteriori privilegi devono essere richiesti a seconda dei flussi di lavoro eseguiti nel notebook.
Registrare un ricevitore webhook del notebook
Per registrare un ricevitore webhook del notebook, precedere nel seguente modo:
- Effettuare l'accesso al portale come amministratore.
- Fare clic su Organizzazione > Impostazioni > webhook > Crea ricevitore webhook.
- Immettere un nome per il ricevitore webhook.
- Selezionare il notebook che verrà eseguito dal ricevitore webhook.
- Immettere una chiave segreta di 32 caratteri che sarà utilizzata per verificare l'origine del webhook.
- Immettere un elenco separato da virgole di intestazioni di firma che verranno controllate per verificare la presenza di un payload crittografato.
- Immettere il token API con privilegi per accedere all'elemento notebook, privilegi di Crea notebook/Crea notebook avanzato e per tutte le altre funzionalità GIS nel notebook.
- Facoltativamente, immettere i parametri in formato JSON.
- Fare clic su Crea ricevitore.
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:
- Utilizzare l'URL del ricevitore webhook, le intestazioni segrete e le intestazioni della firma per creare un webhook di servizio.
- Confermare che il notebook associato con il ricevitore webhook del notebook effettua l'esecuzione ogni volta che è attivato un evento webhook di servizio specifico.
Payload dei webhook servizio
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.
Webhook di feature service
Di seguito è riportato un esempio di playload per un webhook di feature service.
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
}
]
}
Webhook del servizio di geoprocessig
Di seguito è riportato un esempio di playload per un webhook del servizio di geoprocessing.
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
}
]
}