Um webhook é um mecanismo que permite que um aplicativo forneça a outros aplicativos informações sobre eventos. Como um administrador de portal do ArcGIS Enterprise, você pode criar, gerenciar e configurar webhooks. Você pode configurar seus webhooks para notificá-lo automaticamente quando ocorrerem eventos associados aos itens, grupos e usuários do portal. Após um webhook ser ativado, uma solicitação de HTTP é realizada para uma URL única, de carga útil definida pelo usuário para fornecer informações sobre o evento.
Principais termos
A seguir estão os principais termos do webhook:
- Evento do Ativação —A operação que você definiu para ativar seu webhook. Por exemplo, você pode configurar seu webhook para ser ativado quando um grupo específico for atualizado em sua organização ou quando um item for compartilhado. Um webhook pode ter mais de um evento de ativação.
- Carga Útil—Os dados do evento de ativação entregues pelo seu webhook após o evento especificado ter ocorrido. Estas informações são formatadas no JSON. Consulte a seção Carga Útil abaixo para mais informações.
- A URL da Carga Útil—O local onde a carga útil será enviada. A URL da carga útil pode ser criada utilizando um serviço como Microsoft Power Automate, Zapier ou IFTTT. Você também pode criar seu próprio parâmetro de serviço da web personalizado utilizando uma plataforma de sua escolha.
Exemplo de caso de uso
Os webhooks permitem a integração de fluxos de trabalho entre sistemas e há muitas maneiras de aproveitar os webhooks em sua organização.
Monitorar atividade no ArcGIS Enterprise
Um webhook pode ser utilizado para monitorar a atividade no ArcGIS Enterprise. Por exemplo, você pode se inscrever em todos os eventos associados a um item específico. O webhook é ativado quando as propriedades do item são atualizadas e uma solicitação de HTTPS entrega uma carga útil que contém dados que descrevem o evento. Você decide onde esta carga útil é entregue e pode agir de acordo com o recebimento das informações.
Eventos de ativação suportados
Ao criar seu webhook, você está se inscrevendo para ativar eventos. Como estes eventos são operações do portal, a URI para a operação deve ser fornecida na configuração do webhook. As subseções abaixo descrevem os eventos de ativação disponíveis e a URI associada.
Itens
As propriedades do item que podem ser atualizadas variam entre tipos de itens e há ações exclusivas que ativam a operação /update. Por exemplo, se o item for um mapa da web, a atualização da tag, a configuração de um pop-up ou a alteração do mapa base serão todos eventos de atualização que ativarão o webhook.
A seguinte tabela lista os eventos de ativação para itens do portal suportados, que incluem mapas da web, aplicativos da web, camadas, pacotes, documentos PDF e assim por diante:
| Evento de ativação | Exemplo de URI |
|---|---|
Todos os eventos de ativação para todos os itens | /items |
Um item está adicionado ao portal | /items/add |
Nenhum item está excluído | /items/delete |
Nenhum item está atualizado | /items/update |
Nenhum item está movido ou sua propriedade está alterada | /items/move |
Nenhum item está publicado | /items/publish |
Nenhum item está compartilhado | /items/share |
Qualquer item é descompartilhado | /items/unshare |
A propriedade de nenhum item foi reatribuída | /items/reassign |
Todos os eventos de ativação para um item específico | /items/<itemID> |
Um item específico está excluído | /items/<itemID>/delete |
As propriedades de um item específico estão atualizadas | /items/<itemID>/update |
A propriedade de um item específico está alterada ou o item está movido | /items/<itemID>/move |
Um item específico está publicado | /items/<itemID>/publish |
Um item específico está compartilhado | /items/<itemID>/share |
Um item específico está descompartilhado | /items/<itemID>/unshare |
A propriedade de um item específico foi reatribuída | /items/<itemID>/reassign |
Grupos
Quaisquer alterações gerais realizadas nas configurações do grupo constituem uma atualização. Por exemplo, alterar o acesso de um grupo ativará um evento de atualização.
A seguinte tabela lista os eventos de ativação associados aos grupos:
| Evento de ativação | Exemplo de URI |
|---|---|
Todos os eventos de ativação para todos os grupos | /groups |
Um grupo esta adicionado | /groups/add |
Nenhum grupo está atualizado | /groups/update |
Nenhum grupo está excluído | /groups/delete |
Proteção de Exclusão está habilitada para qualquer grupo | /groups/protect |
Proteção de Exclusão está desabilitada para qualquer grupo | /groups/unprotect |
Um usuário é convidado para qualquer grupo | /groups/invite |
Um usuário é adicionado para qualquer grupo | /groups/addUsers |
Um usuário é removido de qualquer grupo | /groups/removeUsers |
Um papel de usuário é atualizado em qualquer grupo | /groups/updateUsers |
A propriedade de nenhum grupo foi reatribuída | /groups/reassign |
Todos os eventos de ativação para um grupo específico | /groups/<groupID> |
Um grupo específico está atualizado | /groups/<groupID>/update |
Um grupo específico está excluído | /groups/<groupID>/delete |
Proteção de Exclusão está habilitada para um grupo específico | /groups/<groupID>/protect |
Proteção de Exclusão está desabilitada para um grupo específico | /groups/<groupID>/unprotect |
Um usuário é convidado para um grupo específico | /groups/<groupID>/invite |
Um usuário é adicionado para um grupo específico | /groups/<groupID>/addUsers |
Um usuário é removido de um grupo específico | /groups/<groupID>/removeUsers |
Um papel de usuário é atualizado em um grupo específico | /groups/<groupID>/updateUsers |
A propriedade para um grupo específico foi reatribuída | /groups/<groupID>/reassign |
Usuários
Um evento de atualização é ativado sempre que uma alteração é realizada no perfil do usuário. No entanto, as alterações realizadas no papel de um usuário, tipo de usuário ou licença não são consideradas uma atualização para o perfil do usuário.
A seguinte tabela lista os eventos de ativação associados aos usuários:
| Evento de ativação | Exemplo de URI |
|---|---|
Todos os eventos de ativação para todos os usuários no portal | /users |
Um usuário é adicionado à organização | /users/add |
Nenhum usuário entrou no portal | /users/signin |
Nenhum usuário saiu do portal | /users/signout |
Nenhum usuário está excluído | /users/delete |
O perfil de nenhum usuário está atualizado | /users/update |
A conta de nenhum usuário está desabilitada | /users/disable |
A conta de nenhum usuário está habilitada | /users/enable |
Nenhum usuário recebeu um novo papel | /users/updateUserRole |
Nenhum usuário recebeu um novo tipo de usuário | /users/updateUserLicenseType |
Todos os eventos de ativação associados a um usuário específico | /users/<username> |
Um usuário especificado entrou no portal | /users/<username>/signIn |
Um usuário especificado saiu do portal | /users/<username>/signOut |
Um usuário específico está excluído | /users/<username>/delete |
Um perfil de usuário específico está atualizado | /users/<username>/update |
Uma conta de usuário específico está desabilitada | /users/<username>/disable |
Uma conta de usuário específico está habilitada | /users/<username>/enable |
Um usuário específico recebeu um novo papel | /users/<username>/updateUserRole |
Um usuário específico recebeu um novo tipo de usuário | /users/<username>/updateUserLicenseType |
Papéis
Um evento de atualização é ativado sempre que uma alteração é realizada em papéis da organização.
A seguinte tabela lista os eventos de ativação associados aos papéis do usuário:
| Evento de ativação | Exemplo de URI |
|---|---|
Todos os eventos de ativação para todos os papéis no portal | /roles |
Um novo papel está criado | /roles/add |
Um papel existente está atualizado | /roles/updated |
Um papel existente está excluído | /roles/delete |
Cargar Útil
Quando um webhook é ativado, uma carga útil é entregue à URL de carga útil específica no formato JSON. Cada evento segue um esquema de JSON semelhante com informações relevantes para o evento.
| Chave | Tipo | Descrição |
|---|---|---|
| webhookName | texto | O nome do webhook que entregou a carga útil. |
| webhookId | texto | O ID do webhook que entregou a carga útil. |
| portalURL | texto | A URL do portal para o qual o webhook está registrado. |
| when | carimbo de hora | A hora na qual a carga útil foi entregue. |
| username | texto | O usuário que ativou o evento. |
| userId | texto | O ID do usuário que ativou o evento. |
| when | carimbo de hora | A hora que ocorreu o evento. |
| operation | texto | A operação executada pelo usuário. Pode ser o seguinte:
|
| source | texto | O tipo de item no qual a operação foi executada. Isto pode ser item, group ou user. |
| id | texto | O ID do item de origem no qual a operação foi executada. |
| properties | objeto | Propriedades adicionais associadas ao evento. Pode ser o seguinte:
|
URL de carga útil
Uma URL de carga útil deve ser fornecida pelo usuário ao criar um webhook; isto define onde a carga será entregue. Como a carga útil é entregue por meio de uma solicitação HTTPS POST, o receptor do webhook deve ser configurado para se comunicar por HTTPS e ser acessado pelo portal. Você pode usar múltiplos serviços da web, como Microsoft Power Automate, Zapier e IFFT, para configurar fluxos de trabalho personalizados com sua carga útil. Por exemplo, você pode criar um fluxo de trabalho para Microsoft Power Automate receber uma carga útil, analisar e formatar a carga útil e a enviar para um de e-mail alternativo. Alternativamente, você pode criar e personalizar seu serviço da web para receber cargas úteis. Para organizações que restringem o acesso à Internet, a criação de um serviço da web personalizado para receber cargas úteis é recomendado. Consulte nossas amostras de SDK Enterprise para um servlet Java pronto para uso.
Exemplo de carga útil
O seguinte é uma amostra de carga útil ilustrando que um grupo específico foi atualizado:
{
"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": {}
}]
}
Criar um webhook
Os webhooks podem ser administrados somente através do ArcGIS Portal Directory (Compartilhando API). Utilize as seguintes etapas para criar um webhook:
- Navegue até o ArcGIS Portal Directory.https://machine.domain.com/webadaptor/sharing/rest
- Entre como um administrador.
Webhooks podem ser criados e gerenciados somente por um administrador.
A página do usuário administrador é exibida.
- Clique no hiperlink ID da Organização ou faça uma solicitação do formulário abaixo, para ir até a página de recursos do Portal Self.https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
- Role até a parte inferior da página, para Webhooks em Recursos Dependentes.https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
- Em Operação Suportada, selecione Create Webhook.
- Especifique os parâmetros para o seu webhook.
Consulte a documentação de REST API do webhook para detalhes sobre estes parâmetros.
Seu webhook agora está listado em webhooks: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks
Gerenciar webhooks
Você pode gerenciar seus webhooks através do ArcGIS Portal Directory, fazendo uma solicitação do seguinte formulário:
https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.
As operações suportadas para gerenciar seus webhooks são as seguintes:
- Update Webhook—Atualiza os parâmetros do seu webhook. Você pode atualizar o nome, URL de carga útil, configuração ou eventos de ativação para o webhook especificado.
- Delete Webhook—Remove o webhook do seu portal.
- Deactivate Webhook e Activate Webhook—Desativa seu webhook, que impede que as cargas sejam entregues quando o webhook é ativado. Quando o webhook é desativado, a operação Ativar Webhook fica disponível para retomar a entrega de cargas úteis.
A página Notification Status exibe informações relacionadas aos eventos de ativação associados ao webhook específico. Você pode utilizar esta tabela para monitorar seu webhook, como também, detalhes de cargas úteis entregues, como a hora na qual o webhook foi ativado e as respostas recebidas da URL de carga útil e da carga útil entregue. Registros indicando a entrega bem-sucedida de uma carga útil são removidos após um dia. Registros que indicam uma tentativa de entrega com falha são armazenados por sete dias.
Consulte o Webhooks API por exemplos destas operações.
Configurar parâmetros avançados
Há vários parâmetros avançados que podem ser utilizados para personalizar ainda mais seus webhooks. Estes parâmetros serão aplicados a todos os webhooks configurados em seu portal e podem ser acessados de https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.
A operação Update permite a você atualizar os seguintes parâmetros:
- Número de tentativas de entrega—Especifica o número de tentativas que serão realizadas para entregar uma carga útil. O padrão são três tentativas e pode ser aumentado até cinco tentativas.
- Tempo limite de notificação—Especifica o período de tempo que uma conexão aguardará para receber uma resposta. Se uma resposta não for recebida dentro deste intervalo, a conexão expirará e será considerada uma tentativa de notificação com falha.
- Tempo decorrido entre tentativas de entrega—Especifica o tempo entre cada tentativa de entrega de carga útil. O padrão são 30 segundos e pode ser aumentado para um máximo de 100 segundos ou diminuído para um mínimo de 1 segundo.
Consulte a documentação do webhooks API para mais informações sobre como configurar parâmetros avançados.
Perguntas mais frequentes de Webhooks
A seguir estão as perguntas comuns encontradas ao usar webhooks.
O ArcGIS Enterprise é desenvolvido em um ambiente desconectado atrás do Firewall da minha organização. Posso ainda configurar webhooks?
Sim. Para configurar webhooks, você deve usar uma URL de carga que pode ser acessada por seu portal. ArcGIS Enterprise. Para fazer isso, você pode construir um aplicativo personalizado e desenvolvê-lo em seu servidor interno.
O que constitui uma atualização de um item, usuário ou grupo?
Se você se inscreveu para receber atualizações de itens, usuários e grupos do portal, o webhook será acionado sempre que suas propriedades forem atualizadas. Por exemplo, se você se inscreveu para atualizações de um item específico em seu portal, seu webhook será acionado se uma atualização for feita no título, tags ou miniatura do item. Uma maneira de determinar se uma ação constitui uma atualização em seu portal é examinar o tráfego da rede. Sempre que uma ação resulta na chamada da operação Atualizar, essa mesma ação também pode acionar um webhook que está escutando atualizações.
Eu estou utilizando Integrated Windows Authentication em meu portal do ArcGIS Enterprise. Posso ainda inscrever no usuário que está entrando e saindo do portal (user/<username>/signIn)?
A partir da versão 10.9, você pode usar o evento acionador /signin para capturar eventos de entrada para autenticação do portal, autenticação de camada da web e logins enterprise.
O que acontece se minha URL de carga útil não funcionar ou se estar indisponível? Há uma forma para recuperar uma carga útil que não foi entregue?
Se o portal tentar entregar uma carga útil para uma URL de carga útil não responsiva ou inalcançável, ou receptor de webhook, os parâmetros avançados que você configurou determinará como e quando o portal tenta outra entrega. Se essas tentativas adicionais também falharem em entregar a carga útil, isso contará como uma falha em relação ao que deactivationPolicy você definiu ao criar o webhook. O webhook é desativado assim que esta política for cumprida.
Você pode ir para o status de notificação do webhook para visualizar todas as tentativas de entregas de carga útil e determinar se eles foram entregues com sucesso ou não.