Вебхуки

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

   

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 по триггерам.

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.

Примечание:

Учетные данные ArcGIS Online, использованные для создания потоков в Power Automate, будут автоматически отключены через две недели. Если вы не можете просмотреть нужные опросы в Power Automate, убедитесь, что ваше подключение для передачи данных в Survey123 активно. Дополнительную информацию см. в статье блога Совет: поддержание корректности токена обновления ArcGIS Connectors for Power Automate.

Чтобы настроить поток в Microsoft Power Automate с использованием коннекторов ArcGIS или ArcGIS Enterprise, выполните следующие действия. Если вы ранее создавали потоки с помощью коннектора Survey123, они по-прежнему будут работать, но новые функции будут добавлены только в коннекторы ArcGIS и ArcGIS Enterprise. Дополнительную информацию см. в статье блога Триггеры и действия Survey123 в ArcGIS connectors for Power Automate.

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

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

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

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

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

   Внимание:

   Выберите опцию При отправке ответа на опрос в ArcGIS, если для выполнения процесса требуется войти в организацию ArcGIS Online. Выберите опцию При отправке ответа на опрос в разделе ArcGIS Enterprise, если для выполнения процесса требуется выполнить вход в организацию ArcGIS Enterprise.

   

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

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

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

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

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

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

   

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

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

13. Щелкните Добавить действие в окне Если да.

    Окно Если нет останется пустым.

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

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

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

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

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

Подсказка:

Вы можете использовать действие Создать отчет, чтобы создать отчет для ответа опроса.

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

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

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

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

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

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

   

4. Предоставьте имя для вебхука, которое будет применяться для его идентификации в будущем.
5. URL полезной информации – адрес, куда будет отсылаться информация опроса. Он должен быть предоставлен внешним сервисом вебхука.

   Когда вы создаете вебхук, используя такой сервис, как Microsoft Power Automate или Make, URL полезной нагрузки автоматически заполняется на этой странице. Другие сервисы, такие как Zapier или FME Server предоставляют 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