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 aggiornamento. 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 scatenante | Esempio 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 scatenante | Esempio 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 scatenante | Esempio 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/singOut |
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 scatenante | Esempio 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.
| Chiave | Tipo | Descrizione |
|---|---|---|
| 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. Può essere:
|
| 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. Può essere:
|
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://machineURL/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. Attenersi alla seguente procedura per creare un webhook:
- Esplorare la directory di Portal for ArcGIS.https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Accedere come amministratore.
I webhook possono essere creati e gestiti solo da un amministratore.
Si visualizza la pagina dell'utente Admin.
- Fare clic sul collegamento ipertestuale ID organizzazione o inviare una richiesta del seguente modulo per andare sulla pagina delle risorse personali del portale.https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Scorrere fino in fondo alla pagina, fino a Webhooks in Risorse figlio.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
- In Operazione supportata, selezionare Create Webhook.
- 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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
Gestire webhook
È possibile gestire i webhook tramite la directory di Portal for ArcGIS inviando una richiesta del seguente modulo:
https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/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
ArcGIS Enterprise è distribuito in un ambiente disconnesso dietro al firewall della mia organizzazione. Posso comunque configurare i webhook?
Sì. Per configurare i webhook, sarà necessario usare un URL di payload 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 attiverà 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 attiverebbe se si apportasse un aggiornamento al titolo, ai tag o all'anteprima dell'elemento. Una maniera semplice per stabilire se un'azione costituisce un aggiornamento nel portale consiste nell'esemplificare il traffico di rete. Ogni volta che un'azione determina il richiamo dell'operazione Aggiorna, quella stessa azione riuscirà 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)?
Questi eventi vengono attivati solo quando un utente accede o si disconnette tramite OAuth. Quindi, Integrated Windows Authentication (IWA) e SAML non sono supportati. Tuttavia, la sicurezza integrata del portale e PKI supportano gli eventi di accesso e disconnessione.
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 conterà come un errore rispetto al deactivationPolicy impostato durante la creazione del webhook. Il webhook si disattiverà 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.