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 scatenante	Esempio di URI	Proprietà
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	sharedToGroups: come viene condiviso un elemento (groupID, Organizzazione o Tutti) Esempi formattati per essere leggibili //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
Si annulla la condivisione di un elemento specifico	/items/<itemID>/unshare	unsharedFromGroups: come viene annullata la condivisione di un elemento (groupID, Organizzazione o Tutti) Esempi formattati per essere leggibili //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
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	Proprietà
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	invitedUserNames: i nomi utente degli utenti invitati in un gruppo Esempio formattato per essere leggibile "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
Un utente viene aggiunto a un gruppo specifico	/groups/<groupID>/addUsers	addedUserNames: i nomi utente degli utenti aggiunti a un gruppo. Esempio formattato per essere leggibile "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
Un utente viene rimosso da un gruppo specifico	/groups/<groupID>/removeUsers	removeUserNames: i nomi utente degli utenti rimossi da un gruppo. Esempio formattato per essere leggibile "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
Il ruolo di un utente viene aggiornato in un gruppo specifico	/groups/<groupID>/updateUsers	updateUserNames: i nomi utente degli utenti i cui ruoli di gruppo sono stati aggiornati Esempio formattato per essere leggibile "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
La proprietà di un gruppo specifico è stata riassegnata	/groups/<groupID>/reassign
Un elemento viene condiviso con un gruppo	/groups/<groupID>/itemShare	sharedItems: il itemID e il tipo elemento dell'elemento condiviso con un gruppo. Esempio formattato per essere leggibile "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
La condivisione di un elemento è terminata per un gruppo specifico	/groups/<groupID>/itemUnshare	unsharedItems: il itemID e il tipo elemento di un elemento la cui condivisione con un gruppo è stata terminata. Esempio formattato per essere leggibile "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

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	Proprietà
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	userRoleUpdatedTo: il nuovo ruolo a cui è stato assegnato l'utente. Esempio formattato per essere leggibile "properties": { "userRoleUpdatedTo": ["New role"] }
È stato assegnato un nuovo tipo di utente a un utente specifico	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo: il nuovo tipo di utente a cui un utente è stato assegnato. Esempio formattato per essere leggibile "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

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	Proprietà
Tutti gli eventi scatenanti per tutti i ruoli nel portale	/roles
Viene creato un nuovo ruolo	/roles/add	name: Il nome del ruolo che è stato creato, aggiornato o eliminato. Esempio formattato per essere leggibile "properties": { "name": ["New role"] }
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. 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.