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 |
指定项目未共享 | /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/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 |
指定用户已被分配了新的用户类型 | /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 | 用户执行的操作。 可为以下内容：
|
| source | string | 执行操作所针对的项目类型。 可以是 item、group 或 user。 |
| id | string | 执行操作所针对的源项目的 ID。 |
| properties | object | 与事件关联的其他属性。 可为以下内容：
|
负载 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 文档。
Webhook 常见问题
以下为使用 webhook 的常见问题。
我的 ArcGIS Enterprise 部署位于组织防火墙后的断开连接的环境中。 这种情况下，我还可以配置 Webhook 吗？
是的。 要配置 Webhook，您必须使用 ArcGIS Enterprise 门户可访问的负载 URL。 要做到这一点，您可以构建自定义应用程序并将其部署在内部服务器上。
项目、用户或组的更新由什么构成？
如果您已订阅门户项目、用户和组的更新，那么只要其属性已更新，您的 Webhook 就会触发。 例如，如果您已订阅门户中特定项目的更新，那么如果项目的标题、标签或缩略图发生更新，您的 Webhook 就会触发。 通过检查网络流量，即可轻松确定某个操作是否为门户更新的组成部分。 无论何时，只要某个操作可导致更新操作被调用，则该操作也能够触发正在监听更新的 Webhook。
我正在 ArcGIS Enterprise 门户中使用集成式 Windows 身份验证。 我还可以订阅用户登录和登出门户 (user/<username>/signIn) 吗？
从 10.9 版本开始，您可以使用 /signin 触发事件为门户身份验证、web 层身份验证和企业登录捕获登录事件。
如果我的负载 URL 出现故障或不可用，将会发生什么？ 有没有办法恢复未传送的负载？
如果门户尝试将负载传送到无法访问或无响应的负载 URL 或 Webhook 接收器，则已设置的高级参数将确定门户尝试另一次传送的方式和时间。 如果这些额外尝试仍无法传送负载，则将视为在创建 Webhook 时设置 deactivationPolicy 失败。 满足此政策后，Webhook 将停用。
您可以转至 Webhook 通知状态以查看所有尝试过的负载传送，并确定它们是否传送成功。