Creare webhook

Un amministratore può configurare webhook per l'installazione di ArcGIS Enterprise per ricevere notifiche quando si verificano eventi specifici. In questa sezione viene illustrato come configurare i webhook dell'organizzazione e del servizio.

Prerequisiti per la creazione di webhook

Prima di creare webhook, verifica i seguenti prerequisiti:

• Per usare i webhook dell'organizzazione, l'organizzazione deve usare ArcGIS Enterprise 10.7 o versione successiva. Per usare i webhook di servizio, l'organizzazione deve usare ArcGIS Enterprise 11.0 o versione successiva.
• Per creare e gestire webhook dell'organizzazione, è necessario disporre del privilegio per i webhook dell'organizzazione o del ruolo di amministratore predefinito.
• Per creare e gestire i webhook dei servizi di geoprocessing, è necessario disporre del privilegio di geoprocessing o del ruolo di amministratore predefinito.

  Nota:

  Gli utenti con privilegio di geoprocessing dovranno disporre anche del privilegio di pubblicazione dei layer basati su server aggiunto al proprio ruolo personalizzato.

• Per creare e gestire i webhook dei feature service, è necessario disporre del privilegio di feature layer o del ruolo di amministratore predefinito.
• I ricevitori di webhook devono essere configurati per comunicare su HTTP. Esistono alcune opzioni sopportate per i destinatari, ad esempio ricevitori di web service di terze parti (Microsoft Power Automate, Zapier e IFFT), web service personalizzati, ArcGIS Notebook Server e ArcGIS Workflow Manager. Per esempi che illustrano come creare web service personalizzati o iniziare a usare i ricevitori di terze parti, consulta Repository di webhook. Per ulteriori informazioni sulla creazione di webhook Notebook Server eWorkflow Manager, consulta Flussi di lavoro automatici con ArcGIS Notebooks e Creare lavori con webhook rispettivamente.
• Per configurare webhook per un feature service, il servizio deve includere la funzionalità di Modifica e il monitoraggio traccia delle modifiche deve essere abilitato senza sincronizzazione.
• Per configurare webhook per il servizio di geoprocessing, il servizio deve essere asincrono.

Creare un webhook dell'organizzazione

I webhook dell'organizzazione consentono di abbonarsi a trigger per eventi associati a elementi, gruppi e utenti del portale ArcGIS Enterprise.

Nota:

I webhook dell'organizzazione possono essere creati tramite il sito Web del portale ArcGIS Enterprise o tramite la ArcGIS Portal Directory. Per una richiesta POST di esempio che crea un webhook su eventi correlati a utenti, gruppi ed elementi, consulta la documentazione della REST API Crea webhook.

Creare un webhook dell'organizzazione nella ArcGIS Portal Directory

Per creare un webhook dell'organizzazione tramite ArcGIS Portal Directory, attenersi alla seguente procedura:

1. Passare a ArcGIS Portal Directory ed effettuare l'accesso come membro con ruolo di amministratore.

   I webhook dell'organizzazione possono essere creati e gestiti solo dagli amministratori con autorizzazione per i webhook dell'organizzazione o da membri a cui è stato assegnato il ruolo di amministratore predefinito.

   https://machine.domain.com/webadaptor/sharing/rest

   Una volta effettuato l'accesso, viene visualizzata la pagina delle risorse Utente per il tuo account.

2. Fai clic sul collegamento ipertestuale ID org oppure effettua una richiesta del seguente modulo per accedere alla pagina delle risorse Autoportale:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Scorri verso il basso nella pagina delle risorse Self e fai clic su Webhook > Crea webhook per accedere all'operazione Crea webhook.
4. Una volta raggiunto l'endpoint Crea webhook, fornisci le seguenti informazioni:
   1. Immetti un nome univoco per il webhook nella casella di testo Nome.
   2. Immetti l'URL di payload per il ricevitore di webhook nella casella di testo URL payload, in qui sarà eseguita un'interrogazione quando viene creato il webhook per garantire che possa essere stabilita la connessione tra il ricevitore e il portale ArcGIS Enterprise.

      Di seguito viene illustrato un esempio di URL di payload:

      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   3. Facoltativamente, imposta un segreto per il webhook che possa essere utilizzato per autenticare i messaggi del webhook con il ricevitore. Inserisci la stringa alfanumerica definita dall'utente nella casella di testo Segreto (facoltativo).
   4. Facoltativamente, specifica le informazioni di disattivazione per il webhook nella casella di testo Proprietà di configurazione.

      Per impostazione predefinita il webhook si disattiva se si verificano cinque errori nel corso di cinque giorni.

   5. In Quali eventi attivano questo webhook, seleziona Definiti manualmente o Inviami tutto.
      • Se scegli Definiti manualmente, elenca gli eventi trigger che saranno utilizzati per questo webhook nella casella di testo Inviami modifiche per questi eventi separati da virgole. Ad esempio, per abbonarti a tutti li eventi relativi a uno specifico gruppo dell'organizzazione, inserisci un evento trigger simile a quello di seguito illustrato, dove [groupID] rappresenta l'ID univoco associato a un gruppo specifico:
        /groups/[groupID]/update

        Per visualizzare un elenco di tutti i trigger di eventi supportati per i webhook di un'organizzazione, consultare Trigger di eventi.
      • Se scegli Inviami tutto, ti abbonerai a tutti gli eventi trigger supportati. Riceverai notifiche per ciascun evento quando si verifica.
5. Una volta configurati i parametri precedenti, fai clic su Crea webhook per inviare la richiesta.

   Una volta completata l'operazione, un nuovo webhook sarà aggiunto all'organizzazione.

Creare un webhook dell'organizzazione nel sito Web del portale ArcGIS Enterprise

Per creare un webhook dell'organizzazione tramite il sito Web del portale ArcGIS Enterprise, attenersi alla seguente procedura:

1. Verificare di aver effettuato l'accesso come amministratore predefinito o come ruolo personalizzato con il privilegio di webhook organizzazione.
2. Accedi a Organizzazione > Impostazioni > Webhook.
3. Fare clic su Crea webhook.
4. Nella finestra Crea webhook, eseguire le seguenti operazioni:
   1. Immetti un nome univoco per il webhook nella casella di testo Nome.
   2. Selezionare un tipo di webhook dal menu a discesa Tipo.
      • Selezionando Tutti si effettua la sottoscrizione a tutti i trigger di eventi supportati. Riceverai notifiche per ciascun evento quando si verifica.
      • Selezionare Elementi, Utenti, Gruppi o Ruoli consente di definire manualmente a quali eventi di trigger si desidera effettuare la sottoscrizione.
   3. Se si seleziona un tipo di webhook diverso da Tutti, comparirà un ulteriore menu a discesa relativo al tipo di webhook che è stato scelto. Ad esempio, se si è selezionato Elementi per il tipo di webhook, compare il menu a discesa Elementi che consente di selezionare un elemento specifico che verrà monitorato dal webhook.
   4. Selezionare un evento di trigger dal menu a discesa Eventi. Ad esempio, se si desidera che il webhook venga invocato quando un elemento specifico viene pubblicato, selezionare /items/<ID elemento>/publish.
   5. Selezionare un tipo di ricevitore webhook.
      • Se si seleziona URL webhook, fornire l'URL di payload per il ricevitore webhook. Di seguito viene illustrato un esempio di URL di payload:
        https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

      • Se si seleziona Notebook, scegliere il notebook che verrà eseguito quando il webhook verrà attivato.

        Nota:

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

   6. Facoltativamente, impostare un valore segreto per il webhook nella casella di testo Segreto (facoltativo). Il valore segreto sarà incluso nel payload del webhook e utilizzato per autenticare i messaggi del webhook con il ricevitore.
5. Fare clic su Crea webhook.

Configurare parametri avanzati per i webhook dell'organizzazione

Le impostazioni avanzate applicate ai webhook dell'organizzazione consentono di personalizzare ulteriormente le prestazioni dei webhook, ad esempio specificando il numero di tentativi di consegna, l'ora di notifica e il tempo tra tentativi di consegna.

Nota:

È possibile modificare le proprietà avanzate dei webhook dell'organizzazione tramite il sito Web del portale ArcGIS Enterprise o la ArcGIS Portal Directory. Per visualizzare una richiesta POST di esempio che configura queste proprietà avanzate, consulta la documentazione della REST API Aggiorna impostazioni webhook.

Configurare i parametri avanzati nella ArcGIS Portal Directory

Per impostare proprietà avanzate tramite la ArcGIS Portal Directory, eseguire le seguenti operazioni:

1. Passare a ArcGIS Portal Directory ed effettuare l'accesso come membro con ruolo di amministratore.

   I webhook dell'organizzazione possono essere creati e gestiti solo dai membri a cui è stato assegnato il ruolo di amministratore predefinito o i membri a cui è stato assegnato il privilegio dei webhook dell'organizzazione.

   https://machine.domain.com/webadaptor/sharing/rest

   Una volta effettuato l'accesso, viene visualizzata la pagina delle risorse Utente per il tuo account.

2. Fai clic sul collegamento ipertestuale ID org oppure effettua una richiesta del seguente modulo per accedere alla pagina delle risorse Autoportale:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Scorri verso il basso nella pagina delle risorse Self e fai clic su Webhook > Impostazioni > Aggiorna per accedere all'operazione Aggiorna impostazioni webhook.
4. Una volta raggiunto l'endpoint Aggiorna impostazioni webhook, fornisci le seguenti informazioni:
   1. Imposta un valore per Numero di tentativi di notifica.

      Il valore specifica il numero di tentativi che saranno effettuati per consegnare i payload di webhook. Per impostazione predefinita il portale ArcGIS Enterprise tenta di consegnare i payload 3 volte. Il valore specificato per i tentativi deve essere un intero da 0 a 5.

   2. Imposta un valore per Timeout notifica in secondi.

      Questo valore specifica il tempo, in secondi, per cui il portale ArcGIS Enterprise attende di ricevere una risposta dal ricevitore. Per impostazione predefinita, il portaleArcGIS Enterprise attende 10 secondi. Il valore per il numero di secondi di attesa del portale ArcGIS Enterprise deve essere un intero da 0 a 60 secondi.

   3. Imposta un valore per Tempo trascorso notifica in secondi.

      Questo valore specifica la quantità di tempo, in secondi, tra due tentativi di consegna del payload. Per impostazione predefinita, il portale ArcGIS Enterprise tenta la consegna del payload dopo 5 secondi se il tentativo precedente non riesce fino a raggiungere il numero massimo di tentativi specificato in Numero di tentativi di notifica.

5. Una volta configurati i parametri precedenti, fai clic su Aggiorna impostazioni webhook per inviare la richiesta.

   Al termine dell'operazione, le proprietà aggiornate saranno applicate a ogni webhook dell'organizzazione specificato.

Configurare i parametri avanzati nel sito Web del portale ArcGIS Enterprise

Per impostare proprietà avanzate tramite il sito Web del portale ArcGIS Enterprise, eseguire le seguenti operazioni:

1. Effettuare l'accesso all'organizzazione come amministratore predefinito o come ruolo personalizzato con il privilegio di webhook organizzazione.
2. Nella parte superiore della schermata del sito, fare clic su Organizzazione e scegliere la scheda Impostazioni.
3. Fare clic su Webhook sul lato sinistro della pagina.
4. Fare clic su Impostazioni avanzate webhook.
5. Nella finestra Impostazioni webhook avanzate, eseguire le seguenti operazioni:
   1. Impostare un valore per Numero di tentativi di consegna.

      Il valore specifica il numero di tentativi che saranno effettuati per consegnare i payload di webhook. Per impostazione predefinita il portale ArcGIS Enterprise tenta di consegnare i payload 3 volte. Il valore specificato per i tentativi deve essere un intero da 0 a 5.

   2. Impostare un valore per Timeout notifica.

      Questo valore specifica il tempo, in secondi, per cui il portale ArcGIS Enterprise attende di ricevere una risposta dal ricevitore. Per impostazione predefinita, il portale ArcGIS Enterprise attenderà 10 secondi. Il valore per il numero di secondi di attesa del portale ArcGIS Enterprise deve essere un intero da 0 a 60 secondi.

   3. Impostare un valore per Tempo trascorso notifica.

      Questo valore specifica la quantità di tempo, in secondi, tra due tentativi di consegna del payload. Per impostazione predefinita, il portale ArcGIS Enterprise tenta di consegnare il payload dopo 5 secondi se il tentativo precedente non riesce fino a raggiungere il numero massimo di tentativi specificato in Numero di tentativi di consegna.

6. Una volta configurate le precedenti impostazioni, fare clic su Salva.

   Le proprietà aggiornate verranno applicate a tutti i webhook configurati dell'organizzazione.

Creare un webhook del servizio di geoprocessing

I webhook del servizio di geoprocessing consentono di abbonarsi a specifici trigger di eventi con i servizi di geoprocessing.

Nota:

I webhook dei servizi di geoprocessing possono essere creati solo tramite la Administrator Directory di ArcGIS Server. Per vedere un esempio di richiesta POST che crea un webhook di servizio di geoprocessing, consultare la documentazione REST API Creare il webhook .

Per creare un webhook per il servizio di geoprocessing, effettua questi passaggi:

1. Passare a ArcGIS Server Administrator Directory e accedere come membro con i privilegi appropriati assegnati.
   I webhook possono essere creati e gestiti solo dai membri a cui è stato assegnato il privilegio di geoprocessing o il ruolo di amministratore predefinito.

   Nota:

   Gli utenti con privilegio di geoprocessing dovranno disporre anche del privilegio di pubblicazione dei layer basati su server aggiunto al proprio ruolo personalizzato.

   https://machine.domain.com/webadaptor/admin

2. Una volta eseguito l'accesso, passa alla risorsa Webhook per un servizio di geoprocessing facendo clic su Servizi > [NomeServizio] > Webhook > Crea, dove [ServiceName] rappresenta il servizio per cui sarà creato il webhook. Per i servizi ospitati in specifiche cartelle, fai clic su Servizi > [NomeCartella] > [NomeServizio] > Webhook > Crea, dove [FolderName] rappresenta la cartella in cui si trova il servizio.

   Attenzione:

   Per configurare webhook per il servizio di geoprocessing, il servizio d geoprocessing deve essere asincrono.

3. Una volta raggiunto l'endpoint Crea webhook, fornisci le seguenti informazioni:
   1. Immetti un nome univoco per il webhook nella casella di testo Nome. Il nome fornito può includere solo valori alfanumerici; i caratteri speciali determineranno un messaggio di errore.
   2. Facoltativamente, imposta un segreto per il webhook che possa essere utilizzato per autenticare i messaggi del webhook con il ricevitore. Digita la stringa alfanumerica definita dall'utente nella casella di testo Chiave di firma.

      I webhook di servizio usano la verifica della firma per garantire l'integrità e la sicurezza dei payload di webhook inviati da ArcGIS Enterprise a un destinatario di webhook. La stringa alfanumerica inserita nella casella di testo Chiave di firma viene trattata come chiave segreta, che è nota, e archiviata in maniera indipendente sia da ArcGIS Enterprise che dal destinatario di webhook. Quando un evento di webhook viene attivato, viene eseguito l'hash di chiave segreta e payload tramite algoritmo HMAC-SHA256, creando la firma. La firma viene quindi passata nella richiesta di webhook come valore dell'intestazione x-esriHook-Signature. Quando il payload di webhook viene consegnato al destinatario, il destinatario utilizza la chiave segreta e il payload per creare una firma utilizzando lo stesso algoritmo HMAC-SHA256 utilizzato da ArcGIS Enterprise. Se la firma inclusa nell'intestazione della richiesta corrisponde al valore ricalcolato creato dal destinatario di webhook, il payload di webhook può essere ritenuto attendibile dal destinatario. In caso contrario, il destinatario può scegliere di rifiutare il payload di webhook in entrata.

   3. Fornisci l'URL di payload per il ricevitore di webhook nella casella di testo URL hook, in cui sarà eseguita l'interrogazione quando viene creato il webhook per garantire che possa essere stabilita la connessione tra il ricevitore eArcGIS Server della distribuzione. Di seguito viene illustrato un payload di esempio:
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   4. Opzionalmente, specifica il tipo di supporto. Nel menu a discesa Tipo di contenuto, scegli una delle seguenti opzioni:
      • application/json (predefinito)
      • application/x-www-form-urlencoded
   5. Facoltativamente, definisci il formato del payload. Nel menu a discesa Formato payload, scegli una delle seguenti opzioni:
      • JSON (predefinito)
      • PJSON
   6. Facoltativamente, usa il parametro Attivo per disabilitare o abilitare le richiamate quando viene attivato il webhook. Per abilitare, seleziona Vero. Per disabilitare, seleziona Falso.

      Per impostazione predefinita le richiamate sono abilitate.

4. Una volta configurati i parametri precedenti, fai clic su Crea per inviare la richiesta.

   Al termine dell'operazione, un nuovo webhook viene applicato allo specifico servizio di geoprocessing.

Nota:

Diversamente dai webhook dell'organizzazione e feature service, i webhook del servizio di geoprocessing non presentano trigger di eventi definiti dall'utente. I webhook del servizio di geoprocessing consegnano i payload una volta completato il processo di geoprocessing. Per ulteriori informazioni sui payload consegnati per i servizi di geoprocessing, consultare Payload.

Creare un webhook di feature service

I webhook di feature service consentono di abbonarsi a specifici trigger di eventi associati ai feature service.

Nota:

I webhook dei feature service possono essere creati solo tramite la Administrator Directory di ArcGIS Server. Per vedere un esempio di richiesta POST che crea un webhook di un feature service, consultare la documentazione REST API Creare il webhook .

Per creare un webhook per un feature service servizio, effettua questi passaggi:

1. Passare a ArcGIS Server Administrator Directory e accedere come membro con i privilegi appropriati assegnati.
   I webhook possono essere creati e gestiti solo dai membri a cui è stato assegnato il privilegio di feature layer o il ruolo di amministratore predefinito.
   https://machine.domain.com/webadaptor/admin

2. Una volta eseguito l'accesso, passa alla risorsa Webhook per un feature service facendo clic su Servizi > [NomeServizio] > Webhook > Crea, dove [ServiceName] rappresenta il servizio per cui sarà creato il webhook. Per i servizi ospitati in specifiche cartelle, fai clic su Servizi > [NomeCartella] > [NomeServizio] > Webhook > Crea, dove [FolderName] rappresenta la cartella in cui si trova il servizio.

   Attenzione:

   Per configurare webhook per un feature service, il feature service deve includere la funzionalità di Modifica e il monitoraggio traccia delle modifiche deve essere abilitato senza sincronizzazione.

3. Una volta raggiunto l'endpoint Crea webhook, fornisci le seguenti informazioni:
   1. Immetti un nome univoco per il webhook nella casella di testo Nome. Il nome fornito può includere solo valori alfanumerici; i caratteri speciali determineranno un messaggio di errore.
   2. Elenca i trigger di eventi che saranno utilizzati per questo webhook nella casella di testo Tipo di modifica. Ad esempio, per richiamare il webhook quando viene creato un feature service, utilizza il seguente trigger di eventi:

      Esempio

      FeaturesCreated

      Per visualizzare un elenco di tutti i trigger di eventi supportati dai webhook di feature service, consultare Trigger di eventi.
   3. Facoltativamente, imposta un segreto per il webhook che possa essere utilizzato per autenticare i messaggi del webhook con il ricevitore. Digita la stringa alfanumerica definita dall'utente nella casella di testo Chiave di firma.

      I webhook di servizio usano la verifica della firma per garantire l'integrità e la sicurezza dei payload di webhook inviati da ArcGIS Enterprise a un destinatario di webhook. La stringa alfanumerica inserita nella casella di testo Chiave di firma viene trattata come chiave segreta, che è nota, e archiviata in maniera indipendente sia da ArcGIS Enterprise che dal destinatario di webhook. Quando un evento di webhook viene attivato, viene eseguito l'hash di chiave segreta e payload tramite algoritmo HMAC-SHA256, creando la firma. La firma viene quindi passata nella richiesta di webhook come valore dell'intestazione x-esriHook-Signature. Quando il payload di webhook viene consegnato al destinatario, il destinatario utilizza la chiave segreta e il payload per creare una firma utilizzando lo stesso algoritmo HMAC-SHA256 utilizzato da ArcGIS Enterprise. Se la firma inclusa nell'intestazione della richiesta corrisponde al valore ricalcolato creato dal destinatario di webhook, il payload di webhook può essere ritenuto attendibile dal destinatario. In caso contrario, il destinatario può scegliere di rifiutare il payload di webhook in entrata.

   4. Fornisci l'URL di payload per il ricevitore di webhook nella casella di testo URL hook, in cui sarà eseguita l'interrogazione quando viene creato il webhook per garantire che possa essere stabilita la connessione tra il ricevitore eArcGIS Server della distribuzione. Di seguito viene illustrato un payload di esempio:
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   5. Opzionalmente, specifica il tipo di supporto. Nel menu a discesa Tipo di contenuto, scegli una delle seguenti opzioni:
      • application/json (predefinito)
      • application/x-www-form-urlencoded
   6. Facoltativamente, definisci il formato del payload. Nel menu a discesa Formato payload, scegli una delle seguenti opzioni:
      • JSON (predefinito)
      • PJSON
   7. Facoltativamente, usa il parametro Attivo per disabilitare o abilitare le richiamate quando viene attivato il webhook. Per abilitare, seleziona Vero. Per disabilitare, seleziona Falso.

      Per impostazione predefinita le richiamate sono abilitate.

   8. Regola la pianificazione per i webhook modificando il valore di Secondi nella casella di testo Pianifica. Per i feature service che sperimentano modifiche frequenti, abbassa il valore di Secondi per ricevere webhook più frequenti con meno informazioni sull'evento nel payload. Per i feature service che non sperimentano modifiche frequenti, aumenta il valore della proprietà Secondi per ricevere webhook meno frequenti con più informazioni sull'evento contenute nel payload.

      Il valore minimo, e predefinito, per la pianificazione è 20 secondi.

4. Una volta configurati i parametri precedenti, fai clic su Crea per inviare la richiesta.

   Al termine dell'operazione, un nuovo webhook viene applicato allo specifico feature service.