Наверх

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

В этом разделе

  1. Ключевые термины
  2. Примеры использования
  3. Поддерживаемые инициирующие события
  4. Полезные данные
  5. Целевой URL
  6. Создание вебхука
  7. Управление вебхуками
  8. Настройка дополнительных параметров

Вебхук – это механизм, позволяющий приложению предоставлять другим приложениям информацию, управляемую событиями. Как администратор портала 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://organization.domain.com/context/sharing/rest
  2. Войдите как администратор.

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

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

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

    См. документацию 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 вебхуков.

Отзыв по этому разделу?

В этом разделе
  1. Ключевые термины
  2. Примеры использования
  3. Поддерживаемые инициирующие события
  4. Полезные данные
  5. Целевой URL
  6. Создание вебхука
  7. Управление вебхуками
  8. Настройка дополнительных параметров