Создание вебхуков и управление ими

Вебхук – это механизм, позволяющий приложению предоставлять другим приложениям информацию, управляемую событиями. Как администратор портала ArcGIS Enterprise вы можете создавать вебхуки, управлять ими и настраивать их. Можно настроить вебхуки для автоматического уведомления о событиях, связанных с элементами портала, группами и пользователями. Как только вебхук инициирован, создается запрос HTTP к уникальному, определяемому пользователем URL полезных данных для предоставления информации относительно события.

Ключевые термины

Ключевые термины для вебхуков:

• Создание и управление вебхуками Например, можно настроить вебхук так, чтобы он запускался при обновлении определенной группы в организации или при публикации элемента. У вебхука может быть одно или несколько инициирующих событий.
• Полезные данные – данные инициирующего события, доставленные вебхуком после указанного события. Эта информация форматируется в виде JSON. Для подробной информации см. раздел Полезные данные ниже.
• URL полезных данных – адрес, куда будут отсылаться полезные данные. URL полезных данных можно создать с помощью сервиса, например, Microsoft Power Automate, Zapier или IFTTT. Можно также создать собственную пользовательскую конечную точку веб-сервиса, используя выбранную платформу.

Примеры использования

Вебхуки позволяют интегрировать рабочие процессы между системами, и есть множество способов воспользоваться преимуществами вебхуков в вашей организации.

Отслеживание активности в ArcGIS Enterprise

С помощью вебхуков можно отслеживать активность в ArcGIS Enterprise. Например, можно подписаться на все события, связанные с определенным элементом. Вебхук запускается при обновлении свойств элемента, а запрос HTTPS доставляет полезные данные, описывающие событие. Вы сами решаете, куда доставляются эти полезные данные, и можете действовать соответствующим образом после получения информации.

Поддерживаемые инициирующие события

При создании вебхука вы подписываетесь на инициирующие события. Так как эти события являются операциями портала, в конфигурации вебхука необходимо предоставить URI к операции. В подразделах ниже описываются доступные инициирующие события и связанный URI.

Элементы

Свойства элементов, которые могут быть обновлены, различаются в зависимости от типа элементов, и существуют уникальные действия, запускающие операцию /update. Например, если элемент является веб-картой, обновление тега, настройка всплывающего окна или изменение базовой карты – все это события обновления, которые вызовут вебхук.

В следующей таблице перечислены инициирующие события для поддерживаемых элементов портала, включая веб-карты, веб-приложения, слои, пакеты, документы PDF и т. д:

Задействованное событие	Пример URI	Свойства
Все инициирующие события для всех элементов	/items
Элемент добавлен на портал	/items/add
Любой элемент удален	/items/delete
Любой элемент обновляется	/items/update
Какой-то элемент перемещен или его собственник изменен	/items/move
Любой элемент опубликован	/items/publish
Любой элемент является общим	/items/share
Любой элемент не является общим	/items/unshare
Право собственности на любой элемент было переназначено	/items/reassign
Все инициирующие события для определенного элемента	/items/<itemID>
Определенный элемент удален	/items/<itemID>/delete
Свойства определенного элемента обновлены	/items/<itemID>/update
Право собственности на определенный элемент изменено или он перемещен	/items/<itemID>/move
Определенный элемент опубликован	/items/<itemID>/publish
Определенный элемент является общим	/items/<itemID>/share	sharedToGroups – как элемент был опубликован (groupID, организация или для всех) Примеры, отформатированные для улучшения читаемости //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
Определенный элемент не является общим	/items/<itemID>/unshare	unsharedFromGroups – для кого доступ к элементу был закрыт (groupID, организация или для всех) Примеры, отформатированные для улучшения читаемости //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
Право собственности на определенный элемент было переназначено	/items/<itemID>/reassign

Группы

Любые общие изменения параметров группы представляют собой обновление. Например, изменение доступа группы вызовет событие обновления.

В приведенной ниже таблице перечислены связанные с группами инициирующие события:

Задействованное событие	Пример URI	Свойства
Все инициирующие события для всех групп	/groups
Группа добавлена	/groups/add
Любая группа обновляется	/groups/update
Любая группа удалена	/groups/delete
Защита от удаления включена для любой группы	/groups/protect
Защита от удаления отключена для любой группы	/groups/unprotect
Пользователь приглашен в любую группу	/groups/invite
Пользователь добавлен в любую группу	/groups/addUsers
Пользователь удален из любой группы	/groups/removeUsers
Роль пользователя обновляется в любой группе	/groups/updateUsers
Право собственности на любую группу было переназначено	/groups/reassign
Все инициирующие события для определенной группы	/groups/<groupID>
Определенная группа обновлена	/groups/<groupID>/update
Определенная группа удалена	/groups/<groupID>/delete
Защита от удаления включена для определенной группы	/groups/<groupID>/protect
Защита от удаления отключена для определенной группы	/groups/<groupID>/unprotect
Пользователь приглашен в определенную группу	/groups/<groupID>/invite	invitedUserNames – имена пользователей, приглашенных в группу Пример, отформатированный для улучшения читаемости "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
Пользователь добавлен в определенную группу	/groups/<groupID>/addUsers	addedUserNames – имена пользователей, добавленных в группу. Пример, отформатированный для улучшения читаемости "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
Пользователь удален из определенной группы	/groups/<groupID>/removeUsers	removeUserNames – имена пользователей, удаленных из группы. Пример, отформатированный для улучшения читаемости "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
Роль пользователя обновляется в определенной группе	/groups/<groupID>/updateUsers	updateUserNames – имена пользователей, чьи роли в группе были обновлены Пример, отформатированный для улучшения читаемости "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
Право собственности на определенную группу было переназначено	/groups/<groupID>/reassign
Элемент, опубликованный для группы	/groups/<groupID>/itemShare	sharedItems – itemID и тип элемента, опубликованного для группы. Пример, отформатированный для улучшения читаемости "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
Публикация элемента для конкретной группы отменена	/groups/<groupID>/itemUnshare	unsharedItems – itemID и тип элемента, публикация которого для группы отменена. Пример, отформатированный для улучшения читаемости "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

Пользователи

Событие обновления инициируется при каждом изменении профиля пользователя. Однако изменения, внесенные в роль пользователя, тип пользователя или лицензию, не считаются обновлением профиля пользователя.

В следующей таблице перечислены инициирующие события, связанные с пользователями:

Задействованное событие	Пример URI	Свойства
Все инициирующие события для всех пользователей в портале	/users
Пользователь добавлен в организацию	/users/add
Любой пользователь зашел на портал	/users/signin
Любой пользователь вышел из портала	/users/signout
Любой пользователь удален	/users/delete
Профиль любого пользователя обновлен	/users/update
Учетная запись любого пользователя отключена	/users/disable
Учетная запись любого пользователя включена	/users/enable
Любому пользователю была назначена новая роль	/users/updateUserRole
Любому пользователю был назначен новый тип пользователя	/users/updateUserLicenseType
Все инициирующие события для определенного пользователя	/users/<username>
Указанный пользователь вошел на портал	/users/<username>/signIn
Указанный пользователь вышел с портала	/users/<username>/signOut
Указанный пользователь удален	/users/<username>/delete
Профиль указанного пользователя обновлен	/users/<username>/update
Учетная запись указанного пользователя отключена	/users/<username>/disable
Учетная запись указанного пользователя включена	/users/<username>/enable
Указанному пользователю была назначена новая роль	/users/<username>/updateUserRole	userRoleUpdatedTo – новая роль, которой был назначен пользователь. Пример, отформатированный для улучшения читаемости "properties": { "userRoleUpdatedTo": ["New role"] }
Указанному пользователю был присвоен новый тип пользователя	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo – новая роль, которой был назначен пользователь. Пример, отформатированный для улучшения читаемости "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

Роли

Событие обновления запускается каждый раз, когда вносятся изменения в роли вашей организации.

В следующей таблице перечислены события триггера, связанные с ролями пользователей:

Задействованное событие	Пример URI	Свойства
Все события триггера для всех ролей в портале	/roles
Новая роль создана	/roles/add	name – имя роли, которая была создана, обновлена или удалена. Пример, отформатированный для улучшения читаемости "properties": { "name": ["New role"] }
Существующая роль обновлена	/roles/updated
Существующая роль удалена	/roles/delete

Полезные данные

После инициализации вебхука на определенный URL отправляются полезные данные в формате JSON. Каждое событие следует аналогичной схеме JSON с информацией, относящейся к событию.

Ключ	Тип	Описание
webhookName	string	Имя вебхука, который доставляет полезные данные.
webhookId	string	ID вебхука, который доставляет полезные данные.
portalURL	string	URL портала, на котором зарегистрирован вебхук.
when	timestamp	Время отправки полезных данных.
username	string	Пользователь инициирующий событие.
userId	string	ID пользователя, инициирующего событие.
when	timestamp	Время происшествия события.
operation	string	Операция, выполненная пользователем. Это может быть: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
source	string	Тип элемента, для которого была выполнена операция. Это может быть item, group или user.
id	string	ID источника элемента, для которого была выполнена операция.
properties	object	Дополнительные свойства, связанные с событием. Это может быть: sharedToGroups – как элемент был опубликован (groupID, организация или для всех) unsharedFromGroups – для кого доступ к элементу был закрыт (groupID, организация или для всех) removeUserNames – имена пользователей, удаленных из группы updateUserNames – имена пользователей, чьи роли в группе были обновлены invitedUserNames – имена пользователей, приглашенных в группу addedUserNames – имена пользователей, добавленных в группу userRoleUpdatedTo – новая роль, которой был назначен пользователь reassignedTo – новый пользователь, которому переназначен элемент или группа userLicenseTypeUpdatedTo – новый тип пользователя, которому был назначен пользователь name – имя роли, которая была создана, обновлена или удалена

Целевой URL

При создании вебхука должен быть предоставлен Url полезных данных. Он определяет, куда будут доставлены полезные данные. Так как полезные данные доставляются через запрос POST HTTPS, получатель вебхука должен быть настроен для связи по HTTPS и быть доступным для портала. Вы можете использовать множество веб-сервисов, например, Microsoft Power Automate, Zapier и IFFT, чтобы настроить рабочие процессы для ваших полезных данных. Например, можно создать рабочий процесс, чтобы при получении полезных данных Microsoft Power Automate анализировал и форматировал полезные данные и отправлял их на электронную почту, используя псевдоним почты. Кроме того, можно создать и настроить веб-сервис для приема полезных данных. Для организаций, которые ограничивают доступ к интернету, рекомендуется создать настраиваемый веб-сервис для получения полезных данных. См. наши примеры корпоративных SDK примеры для готового к использованию сервлета Java.

Пример полезных данных

Ниже приведен пример полезных данных, иллюстрирующий обновление определенной группы:

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

Создание вебхука

Вебхуки можно администрировать только в ArcGIS Portal Directory (Sharing API). Используйте следующие шаги, чтобы создать вебхук:

1. Перейдите в ArcGIS Portal Directory.
   https://machine.domain.com/webadaptor/sharing/rest
2. Войдите как администратор.

   Вебхуки могут создаваться и управляться только администратором.

   Появляется страница пользователя администратора.

3. Щелкните гиперссылку Org ID или создайте запрос по форме ниже, чтобы перейти на страницу собственных ресурсов портала.
   https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
4. Прокрутите страницу вниз к Webhooks под Дочерними ресурсами.
   https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
5. Под Поддерживаемая операция выберите Create Webhook.
6. Укажите параметры для вашего вебхука.

   См. документацию REST API для подробной информации о этих параметрах.

   Ваш вебхук теперь появился в списке вебхуков: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks.

Управление вебхуками

Вы можете управлять вебхуками через ArcGIS Portal Directory посредством запросов в следующей форме:

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

Поддерживаются следующие операции управления вебхуками:

• Update Webhook – обновление параметров вебхуков. Вы можете обновить имя, URL полезных данных, конфигурацию или инициирующие события для указанного вебхука.
• Delete Webhook – удаление вебхука из портала.
• Deactivate Webhook и Activate Webhook – деактивация вашего вебхука, которая останавливает получение полезных данных при инициализации вебхука. Если вебхук был деактивизирован, то становится доступной операция Активизировать вебхук, чтобы возобновить получение полезных данных.

На странице Notification Status отображается информация о инициализирующих событиях, связанных с определенным вебхуком. Эту таблицу можно использовать для просмотра ваших вебхуков, а также сведений о полученных полезных данных, таких как время запуска вебхука и ответы, полученные от URL полезных данных, а также доставленные полезные данные. Записи, указывающие на успешную доставку полезных данных, удаляются через один день. Записи о неудачной попытке доставки хранятся в течение семи дней.

Для примеров этих операций см. API вебхуков.

Настройка дополнительных параметров

Существует несколько дополнительных параметров, которые можно использовать для дальнейшей настройки вебхуков Эти параметры будут применены ко всем настроенным вебхукам на портале и доступны из https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.

Операция Update позволяет обновлять следующее параметры:

• Количество попыток доставки – укажите количество попыток доставки полезных данных. Значение по умолчанию – три попытки, и его можно увеличить до пяти попыток.
• Окончание времени уведомления – укажите время ожидания ответа соединением. Если ответ не получен в течение этого интервала, время соединения завершится, и это будет рассматриваться как неудачная попытка уведомления.
• Время между попытками доставки – укажите время между каждой попыткой доставки полезных данных. Значение по умолчанию – 30 секунд, и его можно увеличить до максимума 100 секунд или уменьшить до минимума 1 секунды.

Подробную информацию о настройке дополнительных параметров см. в документации API вебхуков.