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

Вебхук – это механизм, позволяющий приложению предоставлять другим приложениям информацию, управляемую событиями. Администратор портала 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/<itemID>
Удаление определенного элемента	/items/<itemID>/delete
Обновление свойств определенного элемента	/items/<itemID>/update
Перемещение элемента или изменение владельца элемента	/items/<itemID>/move
Публикация определенного элемента	/items/<itemID>/publish
Открытие доступа к определенному элементу	/items/<itemID>/share
Закрытие доступа к определенному элементу	/items/<itemID>/unshare

Группы

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

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

Инициирующее событие	Пример URI
Все инициирующие события для всех групп	/groups
Добавление группы	/groups/add
Все инициирующие события для определенной группы	/groups/<groupID>
Обновление определенной группы	/groups/<groupID>/update
Удаление определенной группы	/groups/<groupID>/delete
Включение Защиты от удаления для определенной группы	/groups/<groupID>/protect
Отключение Защиты от удаления для определенной группы	/groups/<groupID>/unprotect
Приглашение пользователя в определенную группу	/groups/<groupID>/invite
Добавление пользователя в определенную группу	/groups/<groupID>/addUsers
Удаление пользователя из определенной группы	/groups/<groupID>/removeUsers
Обновление роли пользователя в определенной группе	/groups/<groupID>/updateUsers

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

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

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

Инициирующее событие	Пример URI
Все инициирующие события для всех пользователей в портале	/users
Добавление пользователя в организацию	/users/add
Все инициирующие события для определенного пользователя	/users/<username>
Указанный пользователь вошел на портал	/users/<username>/signIn
Указанный пользователь вышел с портала	/users/<username>/signOut
Удаление определенного пользователя	/users/<username>/delete
Обновление профиля определенного пользователя	/users/<username>/update
Отключение учетной записи определенного пользователя	/users/<username>/disable
Включение учетной записи определенного пользователя	/users/<username>/enable

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

После инициализации вебхука на определенный 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 – имена пользователей, добавленных в группу

URL полезных данных

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>.

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

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

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

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

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

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

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

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

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

Часто задаваемые вопросы по Webhooks

Мой ArcGIS Enterprise развернут в автономной среде, за брандмауэром организации. Можно ли настроить Webhooks?

Да. Для настройки Webhooks, необходимо использовать URL-адрес балансировки, который доступен порталу ArcGIS Enterprise. Для этого можно создать собственное приложение и развернуть его на внутреннем сервере.

Что вызывает обновление элемента, пользователя или группы?

Если вы подписаны на обновление элементов портала, пользователей и групп, Webhook срабатывает на обновление свойств этих элементов. Например, если вы подписаны на обновление определенного элемента вашего портала, Webhook сработает, если произошло обновление заголовка элемента, тегов или эскиза. Чтобы определить, проводится ли обновление с портала, можно изучить сетевой трафик. Каждый раз, когда действие приводит к вызову операции Обновить, это же действие также может вызывать запуск Webhook, который следит за обновлениями.

Я использую Integrated Windows Authentication на своем портале ArcGIS Enterprise. Могу ли я подписываться на слежение за входом и выходом пользователей с портала (user/<username>/signIn)?

Эти события срабатывают только когда пользователь применяет OAuth. Поэтому, Integrated Windows Authentication (IWA) и SAML не поддерживаются. Однако встроенная система безопасности портала и PKI поддерживают события входа и выхода.

Что происходит, если URL-адрес балансировки отключается или становится недоступным? Можно ли восстановить балансировку, которая не была доставлена?

Если портал пытается доставить балансировку загрузки по URL-адресу или приемнику Webhook, которые не отвечают или не доступны, способ и время следующей попытки зависят от дополнительных параметров, заданных на портале. Если эти дополнительные попытки также неудачны, они будут считать одним сбоем в deactivationPolicy, заданном при создании Webhook. При наступлении этих условий, Webhook будет деактивирован.

Вы можете открыть статус уведомлений Webhook, чтобы просмотреть все попытки доставки, и определить, были ли они успешны или нет.