Вебхук – это механизм, позволяющий приложению предоставлять другим приложениям информацию, управляемую событиями. Как администратор портала 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 |
Определенный элемент не является общим | /items/<itemID>/unshare |
Право собственности на определенный элемент было переназначено | /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 |
Пользователь добавлен в определенную группу | /groups/<groupID>/addUsers |
Пользователь удален из определенной группы | /groups/<groupID>/removeUsers |
Роль пользователя обновляется в определенной группе | /groups/<groupID>/updateUsers |
Право собственности на определенную группу было переназначено | /groups/<groupID>/reassign |
Пользователи
Событие обновления инициируется при каждом изменении профиля пользователя. Однако изменения, внесенные в роль пользователя, тип пользователя или лицензию, не считаются обновлением профиля пользователя.
В следующей таблице перечислены инициирующие события, связанные с пользователями:
| Задействованное событие | Пример 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 |
Указанному пользователю был присвоен новый тип пользователя | /users/<username>/updateUserLicenseType |
Роли
Событие обновления запускается каждый раз, когда вносятся изменения в роли вашей организации.
В следующей таблице перечислены события триггера, связанные с ролями пользователей:
| Задействованное событие | Пример URI |
|---|---|
Все события триггера для всех ролей в портале | /roles |
Новая роль создана | /roles/add |
Существующая роль обновлена | /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 | Операция, выполненная пользователем. Это может быть:
|
| source | string | Тип элемента, для которого была выполнена операция. Это может быть item, group или user. |
| id | string | ID источника элемента, для которого была выполнена операция. |
| properties | object | Дополнительные свойства, связанные с событием. Это может быть:
|
Целевой 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). Используйте следующие шаги, чтобы создать вебхук:
- Перейдите в ArcGIS Portal Directory.https://organization.domain.com/context/sharing/rest
- Войдите как администратор.
Вебхуки могут создаваться и управляться только администратором.
Появляется страница пользователя администратора.
- Щелкните гиперссылку Org ID или создайте запрос по форме ниже, чтобы перейти на страницу собственных ресурсов портала.https://organization.domain.com/context/sharing/rest/portals/<orgID>
- Прокрутите страницу вниз к Webhooks под Дочерними ресурсами.https://organization.domain/com/context/sharing/rest/portals/<orgID>/webhooks
- Под Поддерживаемая операция выберите Create Webhook.
- Укажите параметры для вашего вебхука.
См. документацию REST API для подробной информации о этих параметрах.
Ваш вебхук теперь появился в списке вебхуков: https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks.
Управление вебхуками
Вы можете управлять вебхуками через ArcGIS Portal Directory посредством запросов в следующей форме:
https://organization.domain.com/context/sharing/rest/<orgID>/webhooks/<webhookID>.
Поддерживаются следующие операции управления вебхуками:
- Update Webhook – обновление параметров вебхуков. Вы можете обновить имя, URL полезных данных, конфигурацию или инициирующие события для указанного вебхука.
- Delete Webhook – удаление вебхука из портала.
- Deactivate Webhook и Activate Webhook – деактивация вашего вебхука, которая останавливает получение полезных данных при инициализации вебхука. Если вебхук был деактивизирован, то становится доступной операция Активизировать вебхук, чтобы возобновить получение полезных данных.
На странице Notification Status отображается информация о инициализирующих событиях, связанных с определенным вебхуком. Эту таблицу можно использовать для просмотра ваших вебхуков, а также сведений о полученных полезных данных, таких как время запуска вебхука и ответы, полученные от URL полезных данных, а также доставленные полезные данные. Записи, указывающие на успешную доставку полезных данных, удаляются через один день. Записи о неудачной попытке доставки хранятся в течение семи дней.
Для примеров этих операций см. API вебхуков.
Настройка дополнительных параметров
Существует несколько дополнительных параметров, которые можно использовать для дальнейшей настройки вебхуков Эти параметры будут применены ко всем настроенным вебхукам на портале и доступны из https://organization.domain.com/context/sharing/rest/portals/<orgID>/webhooks/settings.
Операция Update позволяет обновлять следующее параметры:
- Количество попыток доставки – укажите количество попыток доставки полезных данных. Значение по умолчанию – три попытки, и его можно увеличить до пяти попыток.
- Окончание времени уведомления – укажите время ожидания ответа соединением. Если ответ не получен в течение этого интервала, время соединения завершится, и это будет рассматриваться как неудачная попытка уведомления.
- Время между попытками доставки – укажите время между каждой попыткой доставки полезных данных. Значение по умолчанию – 30 секунд, и его можно увеличить до максимума 100 секунд или уменьшить до минимума 1 секунды.
Подробную информацию о настройке дополнительных параметров см. в документации API вебхуков.
Часто задаваемые вопросы по Webhooks
Ниже приведены общие вопросы, возникающие при использовании вебхуков.
ArcGIS Enterprise развернут в автономной среде, за брандмауэром организации. Можно ли настроить Webhooks?
Да. Для настройки вебхуков, необходимо использовать URL-адрес полезных данных, который доступен порталу ArcGIS Enterprise. Для этого можно создать собственное приложение и развернуть его на внутреннем сервере.
Что вызывает обновление элемента, пользователя или группы?
Если вы подписаны на обновления элементов портала, пользователей и групп, вебхук срабатывает при каждом обновлении их свойств. Например, если вы подписаны на обновление определенного элемента вашего портала, вебхук сработает, если произошло обновление заголовка элемента, тегов или образца. Способ определить, является ли действие обновлением на вашем портале, - это изучить сетевой трафик. Каждый раз, когда действие приводит к вызову операции Обновить, это же действие может вызывать запуск вебхука, который следит за обновлениями.
Я использую Integrated Windows Authentication на своем портале ArcGIS Enterprise. Могу ли я подписываться на слежение за входом и выходом пользователей с портала (user/<username>/signIn)?
Начиная с версии 10.9, вы можете использовать событие триггера /signin для захвата событий входа в систему для аутентификации портала, аутентификации веб-уровня и корпоративного входа в систему.
Что происходит, если URL-адрес полезных данных отключается или становится недоступным? Можно ли восстановить полезные данные, которые не были доставлены?
Если портал пытается доставить полезные данные по URL-адресу или приемнику вебхука, которые не отвечают или не доступны, способ и время следующей попытки зависят от дополнительных параметров, заданных на портале. Если эти дополнительные попытки также неудачны, они будут считаться одним сбоем в deactivationPolicy, заданном при создании вебхука. При наступлении этих условий, вебхук будет деактивирован.
Вы можете открыть статус уведомлений вебхука, чтобы просмотреть все попытки доставки, и определить, были они успешны или нет.