Webhook

Webhook 是一种受到广泛支持的方法,可允许多个应用程序彼此间进行交互,同时使用 HTTP POST 请求在这些应用程序之间传递回调。 有关详细信息,请参阅 webhook 上的 Wikipedia 页面。 webhook 的常见用途包括通过电子邮件或 SMS 发送通知、向社交媒体发布消息、自动将记录写入电子表格,以及更新企业级数据库。

ArcGIS Survey123 中,可以在提交调查响应时设置和激活 webhook。 例如,在向要素图层成功提交信息后,可以调用 webhook 并触发另一个操作,例如发送通知电子邮件、将调查内容附加到电子表格以及发送警告。

尽管您的工作场所可能有自己的 webhook 提供程序,但同时还有各种第三方工作流服务可供使用,例如 Microsoft Power AutomateMake(以前称为 Integromat)、Zapiertray.io。 上述服务均可用于结合 Survey123,以触发自动化过程。 具体来说,Microsoft Power AutomateMake 均具有内置 Survey123 连接器,使您可以轻松将 Survey123 集成到您的 webhook 工作流中,而无需在 Survey123 网站中配置 webhook 或输入负载 URL。

警告:

当您为调查创建或修改 Webhook 时,必须在 Survey123 外业应用程序中更新调查以使更改生效。

您可通过多种方式将 Survey123 用作您工作流中的触发器。 以下三个部分将介绍如何设置 webhook,以便在发送了响应后发送通知电子邮件,该响应包含以特定值回答的问题。

在本主题的末尾列出了 webhook 事件负载中可用的所有属性以供参考。

Make 中设置 webhook

Make(以前称为 Integromat)是一个在线自动化平台。 注册免费帐户即可开始使用。 Make 提供模板以用作在电子邮件通知中包含附件、将记录添加到电子表格以及创建日历项目的起点。

  1. 转到 https://www.make.com/ 并登录。
  2. 方案页面上,单击创建新方案按钮。
  3. 单击屏幕中间的模块图标。 搜索 Survey123 并将其选中。

    选择一个 Survey123 模块。

  4. 选择监视调查触发模块。

    此模块用于在每次提交调查响应时运行方案。

    将出现一个弹出窗口,用于帮助您配置监视调查模块。

    提示:

    创建报告模块可用于生成调查响应的报告。

  5. 单击添加并提供 webhook 的名称。

    此名称对于您正在为其配置 webhook 的调查应该唯一。

  6. 如果您首次在 Make 中使用 Survey123 模块,则需要设置与 ArcGIS 组织的连接。 您只需执行一次,因为 Make 将保存您的信息以供将来使用。 在连接下,单击添加并为 ArcGIS 的连接命名。
    • 要连接到 ArcGIS Online,请单击保存以登录到您的 ArcGIS 组织。
    • 要连接到 ArcGIS Enterprise,请将 Make 注册到您的门户。 有关详细信息,请参阅 Survey123 诀窍:Make 博客文章。
  7. 从 ArcGIS 组织中选择要连接的调查。

    为调查创建 webhook。

  8. 考虑要包含在 webhook 中的选项,然后单击保存

    建议保留所有高级设置的默认值,从而可在自定义 webhook 时为您提供最大的灵活性。

  9. 单击确定

    随即创建您的 webhook 并配置监视调查模块。

  10. 单击监视调查模块右侧的添加另一个模块按钮以将另一个模块连接到该模块。

    添加另一个模块

  11. 搜索 Email,然后选择 Email 模块。
  12. 选择发送电子邮件操作。
  13. 如果您首次在 Make 中使用此模块,请单击添加以设置与电子邮件帐户的连接。 选择连接类型并登录到您的帐户。

    您只需执行一次,因为 Make 将保存您的连接以供将来使用。

  14. 添加收件人电子邮件地址。

    这是触发电子邮件将发送到的电子邮件地址。

  15. 单击主题文本框。 从调查中选择相应字段,以使用随即显示的模块设置面板来构造电子邮件主题。
  16. 在内容文本框中单击。 从调查中选择相应字段,以使用随即显示的模块设置面板来构造电子邮件的内容。 可以使用 HTML 来格式化内容。
  17. 单击确定

    当问题以某种方式得到解答时,此方案需要发送电子邮件;因此您需要提供一个过滤器。

  18. 单击两个模块之间的工具按钮,然后选择设置过滤器

    向您的方案添加过滤器。

  19. 条件文本框中单击,然后从调查中选择要在过滤器中使用的字段。

    定义您的过滤器。

  20. 为条件选择运算符。 在本例中,选择默认值 Equal to
  21. 输入条件的值,然后单击确定
  22. 单击保存以保存您的方案。

    或者,可以单击运行一次以测试您的 webhook。 单击运行一次后,请打开 Survey123 并提交调查,确保调查响应满足过滤条件。 确认收件人将收到电子邮件。

  23. 使用页面左下角的切换按钮以激活方案。 将计划设置为立即以确保每次提交调查响应时,该方案都会运行。

要了解将 Survey123 用作 Make 方案触发器的其他方法,请参阅 Survey123 集成

Microsoft Power Automate 中设置 webhook

Microsoft Power AutomateMicrosoft Office 365 平台上提供的 webhook 服务。

注:

以下步骤描述了如何使用内置 Survey123 连接器为发布到 ArcGIS Online 的调查设置流程。 要将 Microsoft Power Automate 与发布到 ArcGIS Enterprise 的调查一起使用,您将需要设置自定义连接器。 有关详细信息,请参阅操作方法:为 Microsoft Power Automate 创建 ArcGIS Survey123 连接器以与 ArcGIS Enterprise 配合使用知识库文章。

  1. 打开 Microsoft Power Automate
  2. 从页面侧菜单中选择创建
  3. 从空白开始项中选择自动云流

    随即出现构建自动云流对话框。

  4. 为您的流程命名。

    接下来,您需要选择一个触发器。

  5. 在搜索栏中键入Survey123。 选择提交调查响应时

    Microsoft Power Automate 中的 Survey123 连接器

  6. 单击创建
  7. 如果这是您首次在 Microsoft Power Automate 中使用此连接器,请单击登录以使用 ArcGIS 组织凭据进行登录。

    您只需执行一次,因为 Microsoft Power Automate 将保存您的凭据以供将来使用。

  8. 可以从调查的下拉列表中选择要用于 webhook 的调查。

    您现在已经为 webhook 设置了触发器。 但是,如需让 webhook 使用此触发器执行操作,您的流程还需要添加更多的步骤。

    当问题以某种方式得到解答时,此流程需要发送电子邮件;因此您需要提供一个条件。

  9. 单击新建步骤按钮,然后在操作部分顶部选择条件

    Microsoft Power Automation 中的条件 UI

  10. 单击最左侧的文本框以打开一个对话框,以从调查中选择问题或属性。 选择您希望用于限定调查的调查问题。
  11. 中间的文本框是用于选择触发条件的下拉菜单。 因为您所寻求的是精确响应,所以请选择等于
  12. 在最右边的文本框中,键入您希望据此发送通知的问题的值。

    您希望仅在满足该条件时发送此电子邮件。

  13. 请单击如果是框中的添加操作如果否框保留为空。

    许多邮件服务具有可用于此流程的连接器。

  14. 对于本练习,请选择 Office 365 Outlook - 发送电子邮件 (V2)
  15. 如果凭据尚未保存,请使用凭据登录邮件服务。
  16. 填写电子邮件的收件人主题正文字段。

    您可利用在选择文本框时出现的动态内容对话框,根据需要插入调查响应的内容。

  17. 完成电子邮件后,单击保存

您的 webhook 已完成,且在默认情况下处于活动状态。 现在,webhook 将在每次提交具有给定条件的调查响应时运行。

提示:

可以使用创建报告操作生成调查响应的报告。

Survey123 网站中配置 webhook

要在 Survey123 网站中设置 webhook,请完成以下步骤:

  1. 我的调查页面上,从位于调查面板右下角的菜单中选择设置选项卡。
  2. 从左侧菜单中选择 Webhook 部分。

    通过此页面,您可以设置和访问已设置的所有 webhook。 如果在 Survey123 中没有设置任何 webhook,则页面将为空。

  3. 单击添加 Webhook

    随即显示一个新页面,您可以在此页面中设置 webhook 与调查间的交互方式。

    在 Survey123 网站中添加 webhook 页面

  4. 为您的 webhook 提供一个名称,该名称此后将用于识别您的 webhook。
  5. 负载 URL 是调查信息所发送到的位置。 该 URL 需要由外部 webhook 服务提供。

    当您使用诸如 Microsoft Power AutomateMake 等服务创建 webhook 时,将在此页面上自动填充负载 URL。 诸如 Zapier 或 FME Server 等其他服务将提供可供您复制到此页面上的负载 URL。 其他应用程序可能需要您创建专用服务以侦听 webhook。

  6. 触发事件用于描述将调用 webhook 的具体操作。 选择已提交新记录
  7. 事件数据支持您选择将调查中的以下信息包含在负载中:调查信息服务器响应已提交记录用户信息门户信息。 选中调查信息已提交记录选项。
  8. 状态切换按钮用于确定 webhook 在保存时是否处于活动状态。 保留其设置为打开(默认值)。
  9. 单击保存

Webhook 随即可供使用,且在每次提交调查响应时都会运行。 在 webhook 提供程序中设置的规则可以确保仅在满足某些条件时才发送电子邮件。

事件负载属性

Webhook 事件将属性负载作为 JSON 对象发送。 负载的内容将根据调查而有所不同。 下表列出了 JSON 对象中包含的常见属性:

属性描述
eventType

事件类型。 值可以为 addDataeditData

portalInfo

托管调查的 ArcGIS 组织的相关信息。 其中包含以下属性:

  • url
  • token

surveyInfo

生成 webhook 的调查的相关信息。 其中包含以下属性:

  • formItemId
  • formTitle
  • serviceItemId
  • serviceUrl

userInfo

提交调查的用户的 ArcGIS 组织帐户信息。 其中包含以下属性:

  • username
  • firstName
  • lastName
  • fullName
  • email

以下属性将根据调查和事件类型而有所不同:

属性描述
applyEdits

调查提交的应用编辑内容负载。

如果 eventTypeaddData,则将包含 adds

如果 eventTypeeditData,则将包含 updates。 添加新的重复记录时,还将包含 adds

response

applyEdits 操作的响应。 包括操作创建的要素的全局 ID,以及操作是否成功。

feature

提交的调查记录。 其中包含以下属性:

  • attributes
  • geometry
  • layerInfo
  • result
  • repeats
    注:

    repeats 数组中包含的每个对象都是具有 attributesgeometrylayerInforesultrepeatsattachmentsfeature

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