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 de atualizar. 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 |
Adicionar item no portal | /items/add |
Todos os eventos de ativação para um item específico | /items/<itemID> |
Exclui um item específico | /items/<itemID>/delete |
Atualiza as propriedades de um item específico | /items/<itemID>/update |
Move um item ou altera a propriedade do item | /items/<itemID>/move |
Publica um item específico | /items/<itemID>/publish |
Compartilha um item específico | /items/<itemID>/share |
Descompartilha um item específico | /items/<itemID>/unshare |
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 |
Adicionar grupo | /groups/add |
Todos os eventos de ativação para um grupo específico | /groups/<groupID> |
Atualiza um grupo específico | /groups/<groupID>/update |
Exclui um grupo específico | /groups/<groupID>/delete |
Habilita Proteção de Exclusão para um grupo específico | /groups/<groupID>/protect |
Desabilita Proteção de Exclusão para um grupo específico | /groups/<groupID>/unprotect |
Convida um usuário para um grupo específico | /groups/<groupID>/invite |
Adiciona um usuário para um grupo específico | /groups/<groupID>/addUsers |
Remove um usuário de um grupo específico | /groups/<groupID>/removeUsers |
Atualizar o papel de um usuário em um grupo específico | /groups/<groupID>/updateUsers |
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 |
Adicione um usuário à organização | /users/add |
Todos os eventos de ativação associados a um usuário específico | /users/<username> |
Um usuário especificado registrou no portal | /users/<username>/signIn |
Um usuário especificado saiu do portal | /users/<username>/signOut |
Exclui um usuário específico | /users/<username>/delete |
Atualiza um perfil de usuário específico | /users/<username>/update |
Desabilita uma conta de usuário específica | /users/<username>/disable |
Habilita uma conta de usuário específica | /users/<username>/enable |
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 | intervalo 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 | intervalo de hora | A hora que ocorreu o evento. |
| operation | texto | A operação executada pelo usuário. Isto pode ser:
|
| 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. Isto pode ser:
|
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://machineURL/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. Utilize as seguintes etapas para criar um webhook:
- Navegue até o ArcGIS Portal Directory.https://webadaptorhost.domain.com/webadaptorname/sharing/rest
- Entre como um administrador.
Webhooks podem ser criados e gerenciados somente por um administrador.
A página do usuário de administração é 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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
- Role até a parte inferior da página, para Webhooks em Recursos Dependentes.https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
Gerenciar webhooks
Você pode gerenciar seus webhooks através do ArcGIS Portal Directory, fazendo uma solicitação do seguinte formulário:
https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<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://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/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
Meu ArcGIS Enterprise é desenvolvido em um ambiente desconectado atrás do Firewall da minha organização. Posso ainda configurar webhooks?
Sim. Para configurar webhooks, você precisará utilizar uma URL de carga útil que pode ser acessada pelo seu portal do 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ê subscreveu nas atualizações para seus itens do portal, usuários e grupos, seu webhook ativará sempre que suas propriedades forem atualizadas. Por exemplo, se você subscreveu pelas atualizações de um item específico em seu portal, seu webhook ativaria se uma atualização fosse feita para o título do item, tags ou miniatura. Uma forma fácil para determinar se uma ação constitui uma atualização em seu portal é exemplificar seu tráfego de rede. Qualquer momento que uma ação resulta na operação Atualizar sendo chamada, esta mesma ação também poderá ativar um webhook que está escutando as 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)?
Estes eventos são somente ativados quando um usuário entra e sai via OAuth. Portanto, Integrated Windows Authentication (IWA) e SAML não são suportados. Entretanto, a segurança embutida do portal e PKI suportam os eventos de entrar e sair.
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 estas tentativas adicionais também falharem na entrega da carga útil, isto contará como uma falha para o deactivationPolicy que você configurar ao criar o webhook. O webhook após esta política ter sido atendida.
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.