Crear y administrar webhooks—Portal for ArcGIS | Documentación de ArcGIS Enterprise

Un webhook es un mecanismo que permite que una aplicación proporcione información basada en eventos a otras aplicaciones. Como administrador de un portal de ArcGIS Enterprise, puede crear, administrar y configurar webhooks. Puede configurar sus webhooks para que le notifiquen automáticamente cuando sucedan eventos asociados con los elementos, grupos y usuarios del portal. Cuando se desencadena un webhook, se realiza una solicitud HTTP a una URL de carga única definida por el usuario para ofrecer información relacionada con el evento.

Términos clave

A continuación se muestran términos clave de los webhooks:

Evento desencadenador: la operación que configura para desencadenar el webhook. Por ejemplo, puede configurar su webhook para que se desencadene cuando se actualice un grupo específico de su organización o cuando se comparta un elemento. Un webhook puede tener más de un evento desencadenador.
Carga: los datos del evento desencadenador que envía el webhook después de que ocurra el evento especificado. Esta información tiene el formato JSON. Consulte la sección Cargas que aparece a continuación para obtener más información.
URL de carga: la ubicación a la que se enviará la carga. Es posible crear la URL de carga con servicios como Microsoft Power Automate, Zapier o IFTTT. También puede crear su propio extremo de servicio web personalizado con la plataforma que elija.

Ejemplos de casos de uso

Los webhooks permiten la integración de flujos de trabajo en sistemas; existen diversas formas de aprovechar los webhooks en su organización.

Monitorizar actividades en ArcGIS Enterprise

Puede utilizar los webhooks para monitorizar actividades en ArcGIS Enterprise. Por ejemplo, puede suscribirse a todos los eventos asociados con un elemento concreto. El webhook se desencadena cuando se actualizan las propiedades del elemento, y una solicitud HTTPS proporciona una carga con datos que describen el evento. Usted decide el lugar de entrega de esta carga y podrá tomar las medidas adecuadas tras recibir la información.

Eventos desencadenadores compatibles

Cuando crear el webhook, se está suscribiendo a los eventos desencadenadores. Puesto que estos eventos son operaciones del portal, es necesario proporcionar la URI de la operación en la configuración del webhook. Las siguientes subsecciones describen los eventos desencadenadores disponibles y las URI asociadas.

Elementos

Las propiedades del elemento que se pueden actualizar varían entre tipos de elementos y existen acciones únicas que desencadenan la operación /update. Por ejemplo, si el elemento es un mapa web, actualizar la etiqueta, configurar un elemento emergente o cambiar el mapa base son eventos de actualización que desencadenarán el webhook.

La siguiente tabla muestra los eventos desencadenadores de elementos del portal compatibles, lo que incluye mapas web, aplicaciones web, capas, paquetes, documentos PDF, etc.:


Desencadenar evento	Ejemplo de URI	Propiedades
Todos los eventos desencadenadores de todos los elementos	/items
Se agrega un elemento al portal	/items/add
Se elimina cualquier elemento	/items/delete
Se actualiza cualquier elemento	/items/update
Se mueve o se cambia la propiedad de cualquier elemento	/items/move
Se publica cualquier elemento	/items/publish
Se comparte cualquier elemento	/items/share
Se deja de compartir cualquier elemento	/items/unshare
Se ha reasignado la propiedad de cualquier elemento	/items/reassign
Todos los eventos desencadenadores de un elemento específico	/items/<itemID>
Se elimina un elemento específico	/items/<itemID>/delete
Se actualizan las propiedades de un elemento específico	/items/<itemID>/update
Se cambia la propiedad de un elemento específico o se mueve el elemento	/items/<itemID>/move
Se publica un elemento específico	/items/<itemID>/publish
Se comparte un elemento específico	/items/<itemID>/share	sharedToGroups: cómo se comparte un elemento (groupID, Organización o Todos). Ejemplos, formateados para legibilidad `//groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }`
Se deja de compartir un elemento específico	/items/<itemID>/unshare	unsharedFromGroups: cómo se deja de compartir un elemento (groupID, Organización o Todos). Ejemplos, formateados para legibilidad `//Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }`
Se ha reasignado la propiedad de un elemento específico	/items/<itemID>/reassign

Grupos

Todos los cambios generales realizados en la configuración del grupo constituyen una actualización. Por ejemplo, cambiar el acceso de un grupo desencadenará un evento de actualización.

La siguiente tabla muestra los eventos desencadenadores asociados con grupos:


Desencadenar evento	Ejemplo de URI	Propiedades
Todos los eventos desencadenadores de todos los grupos	/groups
Se agrega un grupo	/groups/add
Se actualiza cualquier grupo	/groups/update
Se elimina cualquier grupo	/groups/delete
Protección contra eliminación está habilitada para cualquier grupo	/groups/protect
Protección contra eliminación está deshabilitada para cualquier grupo	/groups/unprotect
Se invita a un usuario a cualquier grupo	/groups/invite
Se agrega un usuario a cualquier grupo	/groups/addUsers
Se elimina un usuario de cualquier grupo	/groups/removeUsers
Se actualiza un rol de usuario en cualquier grupo	/groups/updateUsers
Se ha reasignado la propiedad de cualquier grupo	/groups/reassign
Todos los eventos desencadenadores de un grupo específico	/groups/<groupID>
Se actualiza un grupo específico	/groups/<groupID>/update
Se elimina un grupo específico	/groups/<groupID>/delete
Protección contra eliminación está habilitada para un grupo específico	/groups/<groupID>/protect
Protección contra eliminación está deshabilitada para un grupo específico	/groups/<groupID>/unprotect
Se invita a un usuario a un grupo específico	/groups/<groupID>/invite	invitedUserNames: los nombres de los usuarios invitados a un grupo. Ejemplo, formateado para legibilidad `"properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Se agrega un usuario a un grupo específico	/groups/<groupID>/addUsers	addedUserNames: los nombres de usuario de los usuarios agregados a un grupo. Ejemplo, formateado para legibilidad `"properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Se elimina un usuario de un grupo específico	/groups/<groupID>/removeUsers	removeUserNames: los nombres de usuario de los usuarios eliminados de un grupo. Ejemplo, formateado para legibilidad `"properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Se actualiza un rol de usuario en un grupo específico	/groups/<groupID>/updateUsers	updateUserNames: los nombres de los usuarios cuyos roles de grupo se han actualizado. Ejemplo, formateado para legibilidad `"properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }`
Se ha reasignado la propiedad de un grupo específico	/groups/<groupID>/reassign
Se comparte un elemento con un grupo	/groups/<groupID>/itemShare	sharedItems: itemID y el tipo de elemento compartidos con un grupo. Ejemplo, formateado para legibilidad `"properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }`
Se deja de compartir un elemento con un grupo específico	/groups/<groupID>/itemUnshare	unsharedItems: itemID y el tipo de elemento que se dejan de compartir con un grupo. Ejemplo, formateado para legibilidad `"properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }`

Usuarios

Los eventos de actualización se desencadenan siempre que se realiza un cambio en el perfil del usuario. Sin embargo, los cambios que se realizan en el rol, el tipo o la licencia de un usuario no se consideran una actualización del perfil del usuario.

La siguiente tabla muestra los eventos desencadenadores asociados con usuarios:


Desencadenar evento	Ejemplo de URI	Propiedades
Todos los eventos desencadenadores de todos los usuarios del portal	/users
Se agrega un usuario a la organización	/users/add
Cualquier usuario ha iniciado sesión en el portal	/users/signin
Cualquier usuario ha cerrado sesión en el portal	/users/signout
Se elimina cualquier usuario	/users/delete
Se actualiza cualquier perfil de usuario	/users/update
Se deshabilita cualquier cuenta de usuario	/users/disable
Se habilita cualquier cuenta de usuario	/users/enable
Se asigna un nuevo rol a cualquier usuario	/users/updateUserRole
Se asigna un nuevo tipo de usuario a cualquier usuario	/users/updateUserLicenseType
Todos los eventos desencadenadores asociados con un usuario específico	/users/<username>
Un usuario especificado ha iniciado sesión en el portal	/users/<username>/signIn
Un usuario especificado ha cerrado sesión en el portal	/users/<username>/signOut
Se elimina un usuario específico	/users/<username>/delete
Se actualiza un perfil de usuario específico	/users/<username>/update
Se deshabilita la cuenta de un usuario específico	/users/<username>/disable
Se habilita la cuenta de un usuario específico	/users/<username>/enable
Se asigna un nuevo rol a un usuario específico	/users/<username>/updateUserRole	userRoleUpdatedTo: el nuevo rol asignado al usuario. Ejemplo, formateado para legibilidad `"properties": { "userRoleUpdatedTo": ["New role"] }`
Se asigna un nuevo tipo de usuario a un usuario específico	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo: el nuevo tipo de usuario asignado a un usuario. Ejemplo, formateado para legibilidad `"properties": { "userLicenseTypeUpdatedTo": ["Editor"] }`

Roles

Los eventos de actualización se desencadenan siempre que se realiza un cambio en los roles de la organización.

La siguiente tabla muestra los eventos desencadenadores asociados con roles de usuarios:


Desencadenar evento	Ejemplo de URI	Propiedades
Todos los eventos desencadenadores de todos los roles del portal	/roles
Se crea un nuevo rol	/roles/add	name: el nombre del rol creado, actualizado o eliminado. Ejemplo, formateado para legibilidad `"properties": { "name": ["New role"] }`
Se actualiza un rol existente	/roles/updated
Se elimina un rol existente	/roles/delete

Cargas

Cuando se desencadena un webhook, se envía una carga a la URL de carga específica en formato JSON. Todos los eventos siguen un esquema JSON similar con información relevante del evento.


Clave	Tipo	Descripción
webhookName	cadena de caracteres	El nombre del webhook que envió la carga.
webhookId	cadena de caracteres	El Id. del webhook que envió la carga.
portalURL	cadena de caracteres	La URL del portal en el que se registra el webhook.
when	marca de hora	La hora a la que se envió la carga.
username	cadena de caracteres	El usuario que desencadenó el evento.
userId	cadena de caracteres	El Id. del usuario que desencadenó el evento.
when	marca de hora	La hora a la que se produjo el evento.
operation	cadena de caracteres	La operación que realizó el usuario. Puede tratarse de lo siguiente: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
source	cadena de caracteres	El tipo de elemento en el que se realizó la operación. Puede ser item, group o user.
id	cadena de caracteres	El Id. del elemento de origen en el que se realizó la operación.
properties	objeto	Propiedades adicionales asociadas con el evento. Puede tratarse de lo siguiente: sharedToGroups: cómo se comparte un elemento (groupID, Organización o Todos). unsharedFromGroups: cómo se deja de compartir un elemento (groupID, Organización o Todos). removeUserNames: los nombres de los usuarios eliminados de un grupo. updateUserNames: los nombres de los usuarios cuyos roles de grupo se han actualizado. invitedUserNames: los nombres de los usuarios invitados a un grupo. addedUserNames: los nombres de los usuarios agregados a un grupo. userRoleUpdatedTo: el nuevo rol asignado al usuario. reassignedTo: el nuevo usuario al que se le ha reasignado un elemento o grupo. userLicenseTypeUpdatedTo: el nuevo tipo de usuario asignado a un usuario. name: el nombre del rol creado, actualizado o eliminado.

URL de carga

Es necesario que el usuario proporcione una URL de carga al crear un webhook, ya que define dónde se enviará la carga. Puesto que la carga se envía a través de una solicitud POST de HTTPS, el webhook receptor se debe configurar para comunicarse mediante HTTPS y para que el portal pueda alcanzarlo. Puede usar varios servicios web, como Microsoft Power Automate, Zapier e IFFT, para configurar flujos de trabajo personalizados con su carga. Por ejemplo, puede crear un flujo de trabajo para que cuando Microsoft Power Automate reciba una carga, la analice, la formatee y la envíe a un alias de correo electrónico. De forma alternativa, puede crear y personalizar su servicio web para que reciba cargas. En el caso de organizaciones que restringen el acceso a Internet, se recomienda crear un servicio web personalizado que reciba las cargas. Consulte nuestras muestras de Enterprise SDK para un servlet de Java listo para usar.

Ejemplo de carga

A continuación, se ofrece una carga de muestra que ilustra que un grupo específico se ha actualizado:

{
  "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": {}
    }
  ]
}

Crear un webhook

Los webhooks solo se pueden administrar mediante el Directorio de Portal for ArcGIS (API de uso compartido). Siga estos pasos para crear un webhook:

Vaya al Directorio de Portal for ArcGIS.
https://machine.domain.com/webadaptor/sharing/rest
Inicie sesión como administrador.
Solo los administradores pueden crear y administrar webhooks.
Aparece la página de usuario administrador.
Haga clic en el hipervínculo ID de organización o realice una solicitud del siguiente formulario para ir a la página del recurso Portal Self.
https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
Desplácese al final de la página, a Webhooks, en Recursos secundarios.
https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
En Operaciones compatibles, seleccione Create Webhook.
Especifique los parámetros de su webhook.
Consulte la documentación de la API REST de los webhooks para obtener más información sobre estos parámetros.
Ahora su webhook aparece con los demás: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks.

Administrar webhooks

Puede administrar sus webhooks mediante el Directorio de Portal for ArcGIS si realiza una solicitud del siguiente formulario:

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.

Las operaciones compatibles para administrar sus webhook son:

Update Webhook: actualiza los parámetros del webhook. Puede actualizar el nombre, la URL de carga, la configuración o los eventos desencadenadores del webhook especificado.
Delete Webhook: elimina el webhook del portal.
Deactivate Webhook y Activate Webhook: desactiva el webhook, lo que detiene el envío de las cargas cuando se ha desencadenado el webhook. Cuando se desactiva el webhook, la operación Activar webhook está disponible para reanudar el envío de cargas.

La página Notification Status muestra información relacionada con los eventos desencadenadores asociados con el webhook específico. Puede usar esta tabla para supervisar el webhook y los detalles de las cargas enviadas, por ejemplo, la hora a la que se desencadenó el webhook y las respuestas recibidas de la URL de carga, así como la carga enviada. Los registros que indican el envío correcto de una carga se eliminan a las 24 horas. Los registros que indican un envío fallido se almacenan durante siete días.

Consulte la API de webhooks para ver ejemplos de estas operaciones.

Configurar parámetros avanzados

Existen varios parámetros avanzados que puede utilizar para personalizar aún más sus webhooks. Dichos parámetros se aplicarán a todos los webhooks configurados en su portal y se puede acceder a ellos desde https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.

Mediante la operación Update puede actualizar estos parámetros:

Número de intentos de envío: especifique el número de intentos que se realizarán para enviar una carga. El valor predeterminado son tres y se puede aumentar hasta cinco.
Tiempo de espera de notificación: especifique el periodo de tiempo que tendrá que esperar una conexión para recibir una respuesta. Si no se recibe ninguna respuesta durante este intervalo, la conexión caducará y se considerará un intento de notificación fallido.
Tiempo transcurrido entre intentos de envío: especifique el tiempo entre cada intento de envío de carga. El valor predeterminado es de 30 segundos y se puede aumentar a un máximo de 100 o reducir a un mínimo de 1.

Consulte la documentación de la API de los webhooks para obtener más información sobre cómo configurar parámetros avanzados.

¿Algún comentario sobre este tema?