创建和管理 webhook—Portal for ArcGIS

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

重要术语

以下是 webhook 的关键术语：

触发事件 - 您设置用来触发 webhook 的操作。例如，您可以将 webhook 配置为在更新组织中特定群组或共享项目时触发。 Webhook 可具有多个触发事件。
负载 - 发生指定事件后 webhook 提供的触发事件数据。此信息的格式为 JSON。有关详细信息，请参阅以下负载部分。
负载 URL - 负载将被发送到的位置。可以使用诸如 Microsoft Power Automate、Zapier 或 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	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

负载

触发 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	执行操作所针对的项目类型。可以是 item、group 或 user。
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 Automate、Zapier 和 IFFT）来配置使用负载的自定义工作流。例如，您可以创建工作流，以便在 Microsoft Power Automate 接收负载时解析并格式化负载，然后将其发送到电子邮件别名。或者，您还可以构建和自定义 web 服务来接收负载。对于限制 Internet 访问的组织，建议构建自定义 web 服务来接收负载。有关即用型 Java servlet，请参阅我们的 Enterprise SDK 示例。

负载示例

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

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

创建 webhook

只能通过 ArcGIS Portal Directory（共享 API）对 Webhook 进行管理。使用以下步骤创建 webhook：

浏览至 ArcGIS Portal Directory。
https://machine.domain.com/webadaptor/sharing/rest
以管理员身份登录。
Webhook 只能由管理员创建和管理。
管理员用户页面随即显示。
单击组织 ID 超链接，或根据以下表单提出请求，以转到门户自助资源页面。
https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
滚动至页面底部，直至子资源下的 Webhooks。
https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
在支持的操作下，选择 Create Webhook。
指定 webhook 的参数。
有关这些参数的详细信息，请参阅 webhook REST API 文档。
您的 webhook 现已在 webhook 下列出：https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks。

管理 webhook

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

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>。

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

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

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

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

配置高级参数

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

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

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

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

有关此主题的反馈?