Skip To Content

创建和管理 webhook

Webhook 是一种允许应用程序为其他应用程序提供事件驱动型信息的机制。作为 ArcGIS Enterprise 门户管理员,您可以创建、管理和配置 webhook。您可以将 webhook 配置为在发生与门户项目、群组和用户关联的事件时自动通知您。触发 webhook 后,将向用户定义的唯一负载 URL 发出 HTTP 请求,以提供有关该事件的信息。

重要术语

以下是 webhook 的关键术语:

  • 触发事件 - 您设置用来触发 webhook 的操作。例如,您可以将 webhook 配置为在更新组织中特定群组或共享项目时触发。Webhook 可具有多个触发事件。
  • 负载 - 发生指定事件后 webhook 提供的触发事件数据。此信息的格式为 JSON。有关详细信息,请参阅以下负载部分。
  • 负载 URL - 负载将被发送到的位置。可以使用诸如 Microsoft Power AutomateZapier 或 IFTTT 等服务来创建负载 URL。您还可以使用所选平台创建自己的自定义 web 服务端点。

用例示例

Webhook 允许跨系统集成工作流,并且可通过多种方式来利用组织中的 webhook。

监控 ArcGIS Enterprise 中的活动

Webhook 可用于监控 ArcGIS Enterprise 中的活动。例如,您可以订阅与特定项目关联的所有事件。更新项目属性时会触发 webhook,而 HTTPS 请求会提供包含事件描述数据的负载。您决定提供此负载所至的位置,并可在收到信息后相应地采取行动。

支持的触发事件

创建 webhook 时,您将订阅触发事件。由于这些事件是门户操作,因此必须在 webhook 配置中提供操作的 URI。以下各小节描述了可用的触发事件和关联的 URI。

项目

可以更新的项目属性因项目类型而异,并且存在触发 /update 操作的唯一操作。例如,如果项目是 web 地图,则更新标签、配置弹出窗口或更改底图都是会触发 webhook 的更新事件。

下表列出了支持的门户项目的触发事件,其中包括 web 地图、web 应用程序、图层、软件包、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

负载

触发 webhook 后,负载将以 JSON 格式传送到特定的负载 URL。每个事件都遵循类似的 JSON 模式,其中包含与事件相关的信息。

类型说明
webhookName

string

传送负载的 webhook 的名称。

webhookId

string

传送负载的 webhook 的 ID。

portalURL

string

Webhook 注册的门户的 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

执行操作所针对的项目类型。可以是 itemgroupuser

id

string

执行操作所针对的源项目的 ID。

properties

object

与事件关联的其他属性。可以是:

  • sharedToGroups - 项目共享的方式(groupID、组织或所有人)
  • unsharedFromGroups - 项目取消共享的方式(groupID、组织或所有人)
  • removeUserNames - 从群组中删除的用户的用户名
  • updateUserNames - 群组角色已更新的用户的用户名。
  • invitedUserNames - 受邀加入群组的用户的用户名。
  • addedUserNames - 已添加到群组的用户的用户名
  • userRoleUpdatedTo - 已为用户分配新的角色
  • reassignedTo - 已为项目或群组重新分配新的用户。
  • userLicenseTypeUpdatedTo - 已为用户分配新的用户类型。
  • name - 已创建、更新或删除的角色名称。

负载 URL

创建 webhook 时,负载 URL 必须由用户提供;这定义了负载所传送至的位置。由于负载是通过 HTTPS POST 请求传送的,因此 webhook 接收器应配置为通过 HTTPS 进行通信且可通过门户访问。您可以使用多个 web 服务(例如 Microsoft Power AutomateZapier 和 IFFT)来配置使用负载的自定义工作流。例如,您可以创建工作流,以便在 Microsoft Power Automate 接收负载时解析并格式化负载,然后将其发送到电子邮件别名。或者,您还可以构建和自定义 web 服务来接收负载。对于限制 Internet 访问的组织,建议构建自定义 web 服务来接收负载。有关即用型 Java servlet,请参阅我们的 Enterprise SDK 示例。

负载示例

以下是用来说明特定群组已更新的示例负载:


{
   "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": {}
   }]
}

创建 webhook

只能通过 ArcGIS Portal Directory 对 Webhook 进行管理。使用以下步骤创建 webhook:

  1. 浏览至 ArcGIS Portal Directory。
    https://webadaptorhost.domain.com/webadaptorname/sharing/rest
  2. 以管理员身份登录。

    Webhook 只能由管理员创建和管理。

    管理员用户页面随即显示。

  3. 单击组织 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. 指定 webhook 的参数。

    有关这些参数的详细信息,请参阅 webhook REST API 文档

    您的 webhook 现已在 webhook 下列出。https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks

管理 webhook

您可以根据以下表单提出请求,从而通过 ArcGIS Portal Directory 来管理您的 webhook:

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>

Webhook 管理所支持的操作如下:

  • Update Webhook - 更新您的 webhook 参数。您可以更新指定 webhook 的名称、负载 URL、配置或触发事件。
  • Delete Webhook - 从门户中删除 webhook。
  • Deactivate WebhookActivate Webhook - 禁用 webhook,即在触发 webhook 时停止传送负载。当 webhook 处于禁用状态时,可通过“激活 Webhook”操作恢复负载的传送。

Notification Status 页面用于显示与特定 webhook 关联的触发事件的相关信息。您可以使用此表来监控您的 webhook 以及所传送负载的详细信息,例如触发 webhook 的时间,以及从负载 URL 和所传送负载接收到的响应。指示负载传送成功的记录会于一天后删除。指示传送尝试失败的记录会存储七天。

有关这些操作的示例,请参阅 Webhooks API

配置高级参数

可通过提供的多个高级参数进一步自定义您的 webhook。这些参数将应用于门户中所有已配置的 webhook,并可通过 https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/webhooks/settings. 进行访问

Update 操作可用于更新以下参数:

  • 传送尝试次数 - 指定将尝试传送负载的次数。默认进行三次尝试,最多可增加至五次。
  • 通知超时 - 指定连接用来接收响应的等待时长。如果在此时间间隔内未收到响应,连接则会超时并被视为失败的通知尝试。
  • 传送尝试之间的历时 - 指定每次负载传送尝试之间的间隔时间。默认值为 30 秒,可增加至最大值 100 秒或减少至最小值 1 秒。

有关如何配置高级参数的详细信息,请参阅 webhook API 文档

Webhook 常见问题

我的 ArcGIS Enterprise 部署位于组织防火墙后的断开连接的环境中。这种情况下,我还可以配置 Webhook 吗?

会。要配置 Webhook,您需要使用 ArcGIS Enterprise 门户可访问的有效负载 URL。要做到这一点,您可以构建自定义应用程序并将其部署在内部服务器上。

项目、用户或组的更新由什么构成?

如果您已订阅门户项目、用户和组的更新,那么只要其属性已更新,您的 Webhook 就会触发。例如,如果您已订阅门户中特定项目的更新,那么如果项目的标题、标签或缩略图发生更新,您的 Webhook 就会触发。通过以网络流量为例,即可轻松确定某个操作是否为门户更新的组成部分。无论何时,只要某个操作可导致更新操作被调用,则该操作也能够触发正在监听更新的 Webhook。

我正在 ArcGIS Enterprise 门户中使用集成式 Windows 身份验证。我还可以订阅用户登录和登出门户吗(user/<username>/signIn)?

仅当用户通过 OAuth 登录或登出时才会触发这些事件。因此,不支持集成的 Windows 身份验证 (IWA) 和 SAML。但是,门户的内置安全性和 PKI 可支持登录和登出事件。

如果我的负载 URL 出现故障或不可用,将会发生什么? 有没有办法恢复未传送的负载?

如果门户尝试将负载传送到无法访问或无响应的负载 URL 或 Webhook 接收器,则已设置的高级参数将确定门户尝试另一次传送的方式和时间。如果这些额外尝试仍无法传送负载,则将视为在创建 Webhook 时设置 deactivationPolicy 失败。满足此政策后,Webhook 将停用。

您可以转至 Webhook 通知状态以查看所有尝试过的负载传送,并确定它们是否传送成功。