Criar e gerenciar webhooks—Portal for ArcGIS | Documentação do ArcGIS Enterprise

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 Ativador —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	Propriedades
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	sharedToGroups—Como um item é compartilhado (groupID, Organização ou Todos) Exemplos, formatados para facilitar a leitura `//groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }`
Um item específico está descompartilhado	/items/<itemID>/unshare	unsharedFromGroups—Como um item é descompartilhado (groupID, Organização ou Todos) Exemplos, formatados para facilitar a leitura `//Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }`
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	Propriedades
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	invitedUserNames—Os nomes de usuário dos usuários convidados para um grupo. Exemplo, formatados para facilitar a leitura `"properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Um usuário é adicionado para um grupo específico	/groups/<groupID>/addUsers	addedUserNames—Os nomes de usuário dos usuários que foram adicionados a um grupo. Exemplo, formatados para facilitar a leitura `"properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Um usuário é removido de um grupo específico	/groups/<groupID>/removeUsers	removeUserNames—Os nomes de usuário dos usuários removidos de um grupo. Exemplo, formatados para facilitar a leitura `"properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Um papel de usuário é atualizado em um grupo específico	/groups/<groupID>/updateUsers	updateUserNames—Os nomes de usuário dos usuários cujos papéis do grupo foram atualizados. Exemplo, formatados para facilitar a leitura `"properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }`
A propriedade para um grupo específico foi reatribuída	/groups/<groupID>/reassign
Um item está compartilhado com um grupo	/groups/<groupID>/itemShare	sharedItems—O itemID e tipo de item do item compartilhado com um grupo. Exemplo, formatados para facilitar a leitura `"properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }`
Um item não está compartilhado de um grupo	/groups/<groupID>/itemUnshare	unsharedItems—O itemID e o tipo de item do item não compartilhado de um grupo. Exemplo, formatados para facilitar a leitura `"properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }`

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	Propriedades
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	userRoleUpdatedTo—Um novo papel ao qual o usuário foi atribuído. Exemplo, formatados para facilitar a leitura `"properties": { "userRoleUpdatedTo": ["New role"] }`
Um usuário específico recebeu um novo tipo de usuário	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo—O novo tipo de usuário ao qual um usuário foi atribuído. Exemplo, formatados para facilitar a leitura `"properties": { "userLicenseTypeUpdatedTo": ["Editor"] }`

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	Propriedades
Todos os eventos de ativação para todos os papéis no portal	/roles
Um novo papel está criado	/roles/add	name—O nome do papel que foi criado, atualizado ou excluído. Exemplo, formatados para facilitar a leitura `"properties": { "name": ["New role"] }`
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: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
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: sharedToGroups—Como um item é compartilhado (groupID, Organização ou Todos) unsharedFromGroups—Como um item é descompartilhado (groupID, Organização ou Todos) removeUserNames—Os nomes de usuário dos usuários removidos de um grupo updateUserNames—Os nomes de usuário dos usuários cujos papéis do grupo foram atualizados. invitedUserNames—Os nomes de usuário dos usuários convidados para um grupo. addedUserNames—Os nomes de usuário dos usuários que foram adicionados a um grupo userRoleUpdatedTo—Um novo papel ao qual o usuário foi atribuído. reassignedTo—O novo usuário ao qual um item ou grupo foi reatribuído userLicenseTypeUpdatedTo—O novo tipo de usuário ao qual um usuário foi atribuído. name—O nome do papel que foi criado, atualizado ou excluído

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.

Comentário neste tópico?