Вебхуки

Вебхуки – это широко поддерживаемый метод, позволяющий нескольким приложениям взаимодействовать друг с другом при помощи запросов HTTP POST, чтобы передавать обратные вызовы между ними. Более подробно см. страницу википедии о вебхуках. Обычное применение вебхуков включает в себя отправку уведомлений по email или СМС, публикацию сообщений в социальных сетях, автоматическую запись в электронную таблицу и обновление многопользовательских баз данных.

В ArcGIS Survey123 вебхуки могут быть настроены и активированы при отправке ответа на опрос. Например, после успешной отправки информации в векторный слой вебхук может вызвать и запустить другое действие, такое как отправка уведомления по email, присоединение содержания опроса к электронной таблице и отправка предупреждения.

У вашего рабочего места может быть собственный провайдер вебхуков, а также один из множества сервисов сторонних производителей, таких как Microsoft Power Automate, Make, Zapier и tray.io. Все они могут использоваться для встраивания Survey123 в качестве триггера для автоматизированного процесса. В частности, каждый из Microsoft Power Automate и Make имеет встроенный коннектор Survey123, позволяющий с минимальными трудностями интегрировать Survey123 в рабочий процесс вебхука и без необходимости настраивать вебхук на веб-сайте Survey123 или ввода целевого URL.

Внимание:

Когда вы создаете или изменяете вебхук для опроса, опрос нужно обновить в полевом приложении Survey123, чтобы изменения вступили в силу.

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

В конце этого раздела для справки перечислены все свойства, доступные в полезной нагрузке события вебхука.

Настройка вебхука в Make

Make (ранее Integromat) является онлайн платформой автоматизации. Для начала работы создайте бесплатную учетную запись. Make имеет шаблоны для использования в качестве отправной точки для включения вложений в уведомления по электронной почте, добавления записей в электронные таблицы и создания элементов календаря.

  1. Перейдите на сайт https://www.make.com/ и выполните вход.
  2. На странице Сценарии щелкните кнопку Создать новый сценарий.
  3. Щелкните значок модуля, расположенный в центре экрана. Выполните поиск Survey123 и выберите его.

    Выбор модуля Survey123.

  4. Выберите модуль триггера Посмотреть опрос.

    Этот модуль создан для запуска сценария при каждой отправке ответа на опрос.

    Появится всплывающее окно, которое помогает настроить модуль Посмотреть опрос.

    Подсказка:

    Модуль Создать отчет может использоваться для генерации отчета для ответа опроса.

  5. Щелкните Добавить и введите имя вебхука.

    Это имя должно быть уникальным для опроса, для которого вы настраиваете вебхук.

  6. Если это первое использование модуля Survey123 в Make, настройте подключение к организации ArcGIS. Это необходимо сделать только один раз, так как Make сохраняет эту информацию для будущего использования. В разделе Подключение щелкните Добавить и имя подключения ArcGIS.
    • Чтобы подключиться к ArcGIS Online, щелкните Сохранить, чтобы войти в организацию ArcGIS.
    • Для подключения к ArcGIS Enterprise, зарегистрируйте Make на своем портале. Дополнительные сведения см. в блоге Survey123 Tricks of the Trade: IntegromatMake.
  7. Выберите опрос в организации ArcGIS для подключения.

    Создание вебхука для вашего опроса

  8. Настройте опции для вебхук и щелкните Сохранить.

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

  9. Нажмите OK.

    Ваш вебхук создан, а модуль Посмотреть опрос настроен.

  10. Нажмите кнопку Добавление другого модуля в правой части модуля Посмотреть опрос, чтобы подключить к нему еще один модуль.

    Добавление другого модуля

  11. Выполните поиск Email и выберите модуль Email.
  12. Выберите действие Отправить email.
  13. Если это ваше первое использование модуля в Make, щелкните Добавить, чтобы настроить подключение к вашей учетной записи электронной почты. Выберите тип подключения и выполните вход под вашей учетной записью.

    Это необходимо сделать только один раз, так как Make сохраняет эту информацию для будущего использования.

  14. Добавьте email получателя.

    На этот адрес будет отправляться email по триггерам.

  15. Щелкните в текстовом окне Тема. Выберите поля из вашего опроса, чтобы создать тему вашего электронного письма, используя появившуюся панель настроек модуля.
  16. Щелкните в поле письма. Выберите поля из вашего опроса, чтобы создать содержимое вашего электронного письма, используя появившуюся панель настроек модуля. Вы можете отформатировать содержимое с помощью HTML.
  17. Нажмите OK.

    В этом сценарии необходимо отправлять email, когда ответ на вопрос получен определенным образом, так что необходимо ввести фильтр.

  18. Щелкните кнопку инструментов между двумя модулями, и выберите Настроить фильтр.

    Добавление фильтра в ваш сценарий

  19. Щелкните текстовое поле Условие и выберите поле в опросе, которое вы хотите использовать в фильтре.

    Задание фильтра

  20. Выберите оператор для условия. В данном случае выберите предложенные по умолчанию, Равно.
  21. Введите значение для условия и щелкните ОК.
  22. Нажмите Сохранить, чтобы сохранить сценарий.

    Дополнительно, щелкните Запустить один раз, чтобы проверить вебхук. После щелчка по кнопке Запустить один раз откройте Survey123 и отправьте опрос, убедившись, что ответ на опрос удовлетворяет условию фильтра. Убедитесь, что получатель получил электронное письмо.

  23. Используйте кнопку переключателя в левом нижнем углу страницы, чтобы активировать свой сценарий. Установите расписание на Немедленно, чтобы сценарий выполнялся каждый раз при отправке ответа на опрос.

Дополнительные способы использования Survey123 в виде триггера в сценариях Make см. в статье Интеграция с Survey123.

Настройка вебхука в Microsoft Power Automate

Microsoft Power Automate – это сервис вебхуков, предоставляемый платформой Microsoft Office 365.

Примечание:

Следующие шаги описывают, как настроить поток с помощью встроенного коннектора Survey123 для опросов, опубликованных в ArcGIS Online. Для использования Microsoft Power Automate с опросами, опубликованными в ArcGIS Enterprise, вам потребуется настроить пользовательский коннектор. Для получения дополнительной информации см. Как: создать коннектор ArcGIS Survey123 для Microsoft Power Automate для использования с ArcGIS Enterprise в статье База знаний.

  1. Откройте Microsoft Power Automate.
  2. Выберите Создать в боковом меню страницы.
  3. Выберите Автоматические облачные потоки из опций Начать с пустого.

    Появится диалоговое окно Создайте автоматический облачный поток.

  4. Назовите свой поток.

    Теперь надо выбрать триггер.

  5. Введите Survey123 в поле поиска. Выберите При отправке ответа на опрос.

    Соединитель Survey123 в Microsoft Power Automate

  6. Нажмите Создать.
  7. Если вы впервые используете этот соединитель в Microsoft Power Automate, щелкните Войти, чтобы выполнить вход с учетными данными вашей организации ArcGIS.

    Вам нужно сделать это только один раз, так как Microsoft Power Automate сохранит ваши учетные данные для использования в будущем.

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

    Теперь вы задали триггер для вебхука. Но для того, чтобы вебхук выполнял какие-либо действия с этим триггером, для процесса необходимо больше шагов.

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

  9. Щелкните кнопку Новый шаг и выберите Условие вверху раздела Действия.

    Условие UI в Microsoft Power Automate

  10. Щелкните крайнее левое текстовое поле, чтобы открыть диалоговое окно для выбора вопроса или свойства из вашего опроса. Выберите вопрос в опросе, который хотите использовать для квалификации опроса.
  11. Средняя текстовая строка – это ниспадающее меню для выбора условий для переключения. Поскольку вы ищете точный ответ, выберите равно.
  12. В самой правой текстовой строке введите значение для ответа, по которому хотите отправлять уведомление.

    Вы хотите, чтобы это письмо было отправлено только в том случае, если условие выполнено.

  13. Щелкните Добавить действие в окне Если да. Окно Если нет останется пустым.

    Соединители имеются у многих почтовых служб и могут использоваться в этом потоке.

  14. Для этого упражнения выберите Office 365 Outlook - Отправить сообщение электронной почты (V2).
  15. Войдите в почтовую службу с вашими учетными данными, если они еще не были сохранены.
  16. Заполните поля To, Subject и Body своего электронного письма.

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

  17. Когда заполните сообщение почты, щелкните Сохранить.

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

Настройка вебхука на веб-сайте Survey123

Выполните следующие действия, чтобы настроить вебхук на веб-сайте Survey123:

  1. На странице Мои опросы выберите вкладку Настройки из меню в правом нижнем углу панели опроса.
  2. Выберите раздел Вебхуки в меню слева.

    Эта страница позволяет настраивать и обеспечивать доступ ко всем вебхукам, которые уже заданы. Если вы не настроили никаких вебхуков в Survey123, эта страница пуста.

  3. Щелкните Добавить вебхук.

    Откроется новая страница, на которой можно настроить, как вебхук будет взаимодействовать с вашим опросом.

    Страница Добавить вебхук на веб-сайте Survey123

  4. Предоставьте имя для вебхука, которое будет применяться для его идентификации в будущем.
  5. URL полезной информации – адрес, куда будет отсылаться информация опроса. Он должен быть предоставлен внешним сервисом вебхука.
  6. Событие-триггер описывает, какое определенное действие будет вызывать вебхук. Выберите Новая запись отправлена.
  7. Данные событий позволяют выбрать, какая информация из опроса будет включена в полезную информацию: Информация об опросе, Ответ сервера, Отправленная запись, Информация о пользователе и Информация о портале. Щелкните опции Информация об опросе и Отправленная запись.
  8. Кнопка-переключатель Статус определяет, будет ли вебхук активен при сохранении. Оставьте ее в положении Включено (по умолчанию).
  9. Щелкните Сохранить.

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

Свойства полезных данных события

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

СвойствоОписание
eventType

Тип события. Значения могут быть addData или editData.

portalInfo

Информация об организации ArcGIS, в которой проводится опрос. Она содержит следующие свойства:

  • url
  • token

surveyInfo

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

  • formItemId
  • formTitle
  • serviceItemId
  • serviceUrl

userInfo

Информация об учетной записи организации ArcGIS для пользователя, отправившего опрос. Она содержит следующие свойства:

  • username
  • firstName
  • lastName
  • fullName
  • email

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

СвойствоОписание
applyEdits

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

Если eventType - addData, они будут содержать adds.

Если eventType - editData, они будут содержать updates. При добавлении новой записи повтора она также будет содержать adds.

response

Ответ от операции applyEdits. Он включает global ID для объектов, созданных операцией, и сведения о том, была ли операция успешной или нет.

feature

Отправленная запись опроса. Она содержит следующие свойства:

  • attributes
  • geometry
  • layerInfo
  • result
  • repeats
    Примечание:

    Каждый объект в массиве repeats - feature, который имеет attributes, geometry, layerInfo, result, repeats и attachments.

  • attachments
    • id
    • globalId
    • name
    • contentType
    • size
    • keywords
    • url
    • parentObjectId