Skip To Content

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

Вебхук – это механизм, позволяющий приложению предоставлять другим приложениям информацию, управляемую событиями. Администратор портала 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/singOut

Любой пользователь удален

/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

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

  • 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://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, чтобы просмотреть все попытки доставки, и определить, были ли они успешны или нет.