Skip To Content

Creare e gestire webhook

Un webhook è un meccanismo che consente a un'applicazione di fornire ad altre applicazioni informazioni determinate da eventi. In qualità di amministratore del portale ArcGIS Enterprise, è possibile creare, gestire e configurare i webhook. È possibile configurare i webhook in modo che inviino automaticamente una notifica quando si verificano eventi associati agli elementi, ai gruppi e agli utenti del portale. Una volta attivato un webhook, si invia una richiesta HTTP a un URL payload univoco definito dall'utente per fornire informazioni sull'evento.

Termini chiave

Seguono i termini chiave dei webhook:

  • Evento scatenante: l'operazione impostata per attivare il webhook. Ad esempio, è possibile configurare che il webhook venga attivato quando si aggiorna un gruppo specifico nell'organizzazione o quando si condivide un elemento. Un webhook può possedere più di un evento scatenante.
  • Payload: i dati dell'evento scatenante offerti dal webhook dopo che si è verificato l'evento specificato. Tali informazioni sono formattate in JSON. Consultare la sezione Payload di seguito per maggiori informazioni.
  • URL payload: dove sarà inviato il payload. L'URL payload può essere creato usando un servizio come Microsoft Power Automate, Zapier o IFTTT. È anche possibile creare il proprio endpoint di servizio Web personalizzato usando una piattaforma a propria scelta.

Caso d'uso di esempio

I webhook consentono l'integrazione dei flussi di lavoro nei sistemi e ci sono molti modi di sfruttare i webhook nell'organizzazione.

Monitorare l'attività in ArcGIS Enterprise

È possibile usare un webhook per monitorare l'attività in ArcGIS Enterprise. Ad esempio, è possibile iscriversi a tutti gli eventi associati a un elemento specifico. Il webhook si attiva quando si aggiornano le proprietà dell'elemento e una richiesta HTTPS invia un payload che contiene i dati che descrivono l'evento. È possibile decidere dove inviare tale payload e agire di conseguenza al momento della ricezione delle informazioni.

Eventi scatenanti supportati

Quando si crea il webhook, ci si iscrive ad eventi scatenanti. Dal momento che questi eventi sono operazioni del portale, è necessario fornire l'URI dell'operazione nella configurazione del webhook. Le seguenti sottosezioni descrivono gli eventi scatenanti disponibili e l'URI associato.

Elementi

Le proprietà degli elementi che possono essere aggiornate variano a seconda dei tipi di elementi e ci sono azioni univoche che attivano l'operazione di /update. Ad esempio, se l'elemento è una Web Map, l'aggiornamento del tag, la configurazione di un popup o la modifica della basemap sono tutti eventi di aggiornamento che attivano il webhook.

La seguente tabella elenca gli eventi scatenanti per gli elementi del portale supportati, che includono Web Map, app Web, layer, package, documenti PDF e così via:

Evento scatenanteEsempio di URI

Tutti gli eventi scatenanti per tutti gli elementi

/items

Un elemento viene aggiunto al portale

/items/add

Un elemento qualsiasi viene eliminato

/items/delete

Un elemento qualsiasi viene aggiornato

/items/update

Un elemento qualsiasi viene spostato o se ne cambia la proprietà

/items/move

Un elemento qualsiasi viene pubblicato

/items/publish

Un elemento qualsiasi viene condiviso

/items/share

Si annulla la condivisione di un elemento qualsiasi

/items/unshare

La proprietà di un elemento qualsiasi è stata riassegnata

/items/reassign

Tutti gli eventi scatenanti per un elemento specifico

/items/<itemID>

Un elemento specifico viene eliminato

/items/<itemID>/delete

Si aggiornano le proprietà di un elemento specifico

/items/<itemID>/update

Si modifica la proprietà di un elemento specifico o lo si sposta

/items/<itemID>/move

Un elemento specifico viene pubblicato

/items/<itemID>/publish

Un elemento specifico viene condiviso

/items/<itemID>/share

Si annulla la condivisione di un elemento specifico

/items/<itemID>/unshare

La proprietà di un elemento specifico è stata riassegnata

/items/<itemID>/reassign

Gruppi

Qualunque modifica generale apportata alle impostazioni del gruppo costituisce un aggiornamento. Ad esempio, modificare l'accesso di un gruppo attiverà un evento di aggiornamento.

La seguente tabella elenca gli eventi scatenanti associati ai gruppi:

Evento scatenanteEsempio di URI

Tutti gli eventi scatenanti per tutti i gruppi

/groups

Un gruppo viene aggiunto

/groups/add

Un gruppo qualsiasi viene aggiornato

/groups/update

Un gruppo qualsiasi viene eliminato

/groups/delete

Eliminare protezione è abilitato per qualunque gruppo

/groups/protect

Eliminare protezione è disabilitato per qualunque gruppo

/groups/unprotect

Un utente viene invitato a un gruppo qualsiasi

/groups/invite

Un utente viene aggiunto a un gruppo qualsiasi

/groups/addUsers

Un utente viene rimosso da un gruppo qualsiasi

/groups/removeUsers

Il ruolo di un utente viene aggiornato in un gruppo qualsiasi

/groups/updateUsers

La proprietà di un gruppo qualsiasi è stata riassegnata

/groups/reassign

Tutti gli eventi scatenanti per un gruppo specifico

/groups/<groupID>

Un gruppo specifico viene aggiornato

/groups/<groupID>/update

Un gruppo specifico viene eliminato

/groups/<groupID>/delete

Eliminare protezione è abilitato per un gruppo specifico

/groups/<groupID>/protect

Eliminare protezione è disabilitato per un gruppo specifico

/groups/<groupID>/unprotect

Un utente viene invitato a un gruppo specifico

/groups/<groupID>/invite

Un utente viene aggiunto a un gruppo specifico

/groups/<groupID>/addUsers

Un utente viene rimosso da un gruppo specifico

/groups/<groupID>/removeUsers

Il ruolo di un utente viene aggiornato in un gruppo specifico

/groups/<groupID>/updateUsers

La proprietà di un gruppo specifico è stata riassegnata

/groups/<groupID>/reassign

Utenti

Un evento di aggiornamento viene attivato ogni volta che si apporta una modifica al profilo utente. Tuttavia, le modifiche apportate al ruolo di un utente, al tipo di utente o alla licenza non vengono considerate un aggiornamento del profilo utente.

La seguente tabella elenca gli eventi scatenanti associati agli utenti:

Evento scatenanteEsempio di URI

Tutti gli eventi scatenanti per tutti gli utenti nel portale

/users

Un utente viene aggiunto all'organizzazione

/users/add

Un utente qualsiasi ha eseguito l'accesso al portale

/users/signin

Un utente qualsiasi si è disconnesso dal portale

/users/signout

Un utente qualsiasi viene eliminato

/users/delete

Il profilo di un utente qualsiasi viene aggiornato

/users/update

L'account di un utente qualsiasi viene disabilitato

/users/disable

L'account di un utente qualsiasi viene abilitato

/users/enable

È stato assegnato un nuovo ruolo a un utente qualsiasi

/users/updateUserRole

È stato assegnato un nuovo tipo di utente a un utente qualsiasi

/users/updateUserLicenseType

Tutti gli eventi scatenanti associati a un utente specifico

/users/<username>

Un utente specificato ha eseguito l'accesso al portale

/users/<username>/signIn

Un utente specificato si è disconnesso dal portale

/users/<username>/signOut

Un utente specifico viene eliminato

/users/<username>/delete

Il profilo di un utente specifico viene aggiornato

/users/<username>/update

L'account di un utente specifico viene disabilitato

/users/<username>/disable

L'account di un utente specifico viene abilitato

/users/<username>/enable

È stato assegnato un nuovo ruolo a un utente specifico

/users/<username>/updateUserRole

È stato assegnato un nuovo tipo di utente a un utente specifico

/users/<username>/updateUserLicenseType

Ruoli

Un evento di aggiornamento viene attivato ogni volta che si apporta una modifica ai ruoli dell'organizzazione.

La seguente tabella elenca gli eventi scatenanti associati ai ruoli utente:

Evento scatenanteEsempio di URI

Tutti gli eventi scatenanti per tutti i ruoli nel portale

/roles

Viene creato un nuovo ruolo

/roles/add

Viene aggiornato un ruolo esistente

/roles/updated

Viene eliminato un ruolo esistente

/roles/delete

Payload

Una volta attivato un webhook, si invia un payload all'URL payload specifico in formato JSON. Ogni evento segue uno schema JSON simile con informazioni rilevanti per l'evento.

ChiaveTipoDescrizione
webhookName

stringa

Il nome del webhook che ha inviato il payload.

webhookId

stringa

L'ID del webhook che ha inviato il payload.

portalURL

stringa

L'URL del portale in cui è registrato il webhook.

when

timestamp

L'orario in cui viene inviato il payload.

username

stringa

L'utente che ha attivato l'evento.

userId

stringa

L'ID dell'utente che ha attivato l'evento.

when

timestamp

L'orario in cui si è verificato l'evento.

operation

stringa

L'operazione eseguita dall'utente. Possono essere i seguenti:

  • add
  • addUsers
  • delete
  • disable
  • enable
  • invite
  • move
  • protect
  • publish
  • removeUsers
  • share
  • unprotect
  • unshare
  • update
  • updateUsers
source

stringa

Il tipo di elemento su cui si è eseguita l'operazione. Può essere item, group o user.

id

stringa

L'ID dell'elemento di origine su cui si è eseguita l'operazione.

properties

oggetto

Ulteriori proprietà associate all'evento. Possono essere i seguenti:

  • sharedToGroups: come viene condiviso un elemento (groupID, Organizzazione o Tutti)
  • unsharedFromGroups: come viene annullata la condivisione di un elemento (groupID, Organizzazione o Tutti)
  • removeUserNames: i nomi utente degli utenti rimossi da un gruppo
  • updateUserNames: i nomi utente degli utenti i cui ruoli di gruppo sono stati aggiornati
  • invitedUserNames: i nomi utente degli utenti invitati in un gruppo
  • addedUserNames: i nomi utente degli utenti aggiunti a un gruppo
  • userRoleUpdatedTo: il nuovo ruolo a cui è stato assegnato l'utente.
  • reassignedTo: il nuovo utente a cui un elemento o gruppo è stato riassegnato.
  • userLicenseTypeUpdatedTo: il nuovo tipo di utente a cui un utente è stato assegnato.
  • name: Il nome del ruolo che è stato creato, aggiornato o eliminato.

URL payload

Al momento della creazione di un webhook l'utente deve fornire un URL payload: questo definisce dove sarà inviato il payload. Dal momento che il payload viene inviato tramite una richiesta HTTPS POST, il ricevitore del webhook deve essere configurato per comunicare tramite HTTPS ed essere raggiungibile dal portale. È possibile usare più servizi Web, come Microsoft Power Automate, Zapier e IFFT, per configurare flussi di lavoro personalizzati con il payload. Ad esempio, è possibile creare un flusso di lavoro in modo che quando Microsoft Power Automate riceve un payload, analizza e formatta il payload e lo invia all'alias di un'e-mail. In alternativa, è possibile creare e personalizzare il servizio Web perché riceva payload. Per le organizzazioni che limitano l'accesso a Internet, si consiglia di creare un servizio Web personalizzato per la ricezione dei payload. Consultare i nostri esempi Enterprise SDK per un servlet Java pronto all'uso.

Esempio di payload

Segue un esempio di payload che illustra che si è aggiornato un gruppo specifico:


{
   "info": {
      "webhookName": "Group monitoring",
      "webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
      "portalURL": "https://orgURL/portal/",
      "when": 1543192196521
   },
   "events": [{
      "username": "administrator",
      "userId": "173dd04b69134bdf99c5000aad0b6298",
      "when": 1543192196521,
      "operation": "update",
      "source": "group",
      "id": "173dd04b69134bdf99c5000aad0b6298",
      "properties": {}
   }]
}

Creare un webhook

I webhook possono essere amministrati solo tramite la directory di Portal for ArcGIS (Condividendo l'API). Attenersi alla seguente procedura per creare un webhook:

  1. Esplorare la directory di Portal for ArcGIS.
    https://machine.domain.com/webadaptor/sharing/rest
  2. Accedere come amministratore.

    I webhook possono essere creati e gestiti solo da un amministratore.

    Si visualizza la pagina dell'utente amministratore.

  3. Fare clic sul collegamento ipertestuale ID organizzazione o inviare una richiesta del seguente modulo per andare sulla pagina delle risorse personali del portale.
    https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
  4. Scorrere fino in fondo alla pagina, fino a Webhooks in Risorse figlio.
    https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
  5. In Operazione supportata, selezionare Create Webhook.
  6. Specificare i parametri per il webhook.

    Consultare il webhook Documentazione dell'API REST per maggiori informazioni su questi parametri.

    Il webhook è adesso elencato tra i webhook: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks

Gestire webhook

È possibile gestire i webhook tramite la directory di Portal for ArcGIS inviando una richiesta del seguente modulo:

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.

Le operazioni supportate per la gestione dei webhook sono le seguenti:

  • Update Webhook: aggiornare i parametri del webhook. È possibile aggiornare il nome, l'URL payload, la configurazione o gli eventi scatenanti per il webhook specificato.
  • Delete Webhook: rimuovere il webhook dal portale.
  • Deactivate Webhook e Activate Webhook: disattivare il webhook, che impedisce l'invio dei payload all'attivazione del webhook. Quando il webhook è disattivato, è disponibile l'operazione Attivare webhook per riprendere la consegna di payload.

La pagina Notification Status visualizza informazioni correlate a eventi scatenanti associati al webhook specifico. È possibile usare questa tabella per monitorare il webhook nonché i dettagli dei payload consegnati, come l'orario di attivazione del webhook e le risposte ricevute dall'URL payload e dal payload inviato. I record che segnalano l'avvenuta consegna di un payload vengono rimossi dopo un giorno. I record che segnalano un tentativo di consegna non riuscito vengono conservati per sette giorni.

Consultare l'API del webhook per visualizzare esempi di tali operazioni.

Configurare i parametri avanzati

Esistono vari parametri avanzati utilizzabili per personalizzare ulteriormente i webhook. Tali parametri saranno applicati a tutti i webhook configurati nel portale e sono accessibili da https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings..

L'operazione Update consente di aggiornare i seguenti parametri:

  • Numero di tentativi di consegna: specificare il numero dei tentativi di consegna di un payload che si effettueranno. Il valore predefinito è tre tentativi e può essere aumentato fino a cinque tentativi.
  • Timeout della notifica: specificare la durata di tempo durante la quale una connessione attenderà la ricezione di una risposta. Se non si riceve una risposta entro questo intervallo, si verificherà il timeout della connessione e il tentativo di notifica sarà considerato non riuscito.
  • Tempo trascorso tra tentativi di consegna: specificare il tempo che intercorre tra un tentativo di consegna di payload e l'altro. Il valore predefinito è 30 secondi e può essere aumentato fino a un massimo di 100 secondi o ridotto fino a un minimo di 1 secondo.

Consultare la documentazione dell'API dei webhook per maggiori informazioni su come configurare i parametri avanzati.

Domande frequenti sui webhook

Le seguenti sono domande frequenti riscontrate durante l'uso di webhook.

ArcGIS Enterprise è distribuito in un ambiente disconnesso dietro al firewall dell'organizzazione. Posso comunque configurare i webhook?

Sì. Per configurare i webhook, è necessario usare un URL di payload che è raggiungibile dal portale ArcGIS Enterprise. A tal fine, è possibile creare un'applicazione personalizzata e installarla sul server interno.

Cosa costituisce un aggiornamento per un elemento, utente o gruppo?

Se è stato effettuato l'abbonamento per ricevere aggiornamenti per gli elementi, gli utenti e i gruppi del portale, il webhook si attiva ogni volta che si aggiornano le loro proprietà. Ad esempio, se è stato effettuato l'abbonamento per ricevere aggiornamenti per un elemento specifico nel portale, il webhook si attiva se si apportasse un aggiornamento al titolo, ai tag o all'anteprima dell'elemento. Un modo per determinare se un'azione è costituita da un aggiornamento nel portale è esaminare il traffico di rete. Ogni volta che un'azione determina il richiamo dell'operazione Aggiorna, quella stessa azione può anche ad attivare un webhook che è in ascolto in attesa di aggiornamenti.

Sto utilizzando Integrated Windows Authentication nel mio portale ArcGIS Enterprise. Posso comunque effettuare l'abbonamento all'accesso e alla disconnessione del portale per l'utente (user/<username>/signIn)?

Iniziando a 10.9, è possibile usare l'evento di azionamento /signin per acquisire eventi di accesso per l'autenticazione del portale, l'autenticazione a livello web e i login aziendali.

Cosa succede se il mio URL di payload non funziona o diventa indisponibile? C'è un modo per ripristinare un payload che non è stato consegnare?

Se il portale cerca di consegnare un payload a un URL di payload o ricevitore webhook irraggiungibile o che non risponde, i parametri avanzati impostati determineranno come e quando il portale proverà un'altra consegna. Se anche con questi tentativi aggiuntivi non si riesce a consegnare il payload, questo conta come un errore rispetto al deactivationPolicy impostato durante la creazione del webhook. Il webhook si disattiva una volta soddisfatto questo criterio.

È possibile andare sullo stato della notifica del webhook per visualizzare tutti i tentativi di consegna di payload e stabilire se sono stati completati correttamente o meno.