创建 webhook

作为组织管理员，您可以为 ArcGIS Enterprise 部署配置 webhook，以在发生特定事件时收到通知。 以下部分概述了如何配置组织和服务 webhook。

创建 webhook 的先决条件

创建 webhook 之前，请考虑以下事项：

• 要使用组织 webhook，您的组织必须使用 ArcGIS Enterprise 10.7 或更高版本。 要使用服务 webhook，您的组织必须使用 ArcGIS Enterprise 11.0 或更高版本。
• 要创建和管理组织 webhook，您必须已被分配组织 webhook 权限或被分配默认管理员角色。
• 要创建和管理地理处理服务 webhook，您必须已被分配地理处理权限或被分配默认管理员角色或发布者角色。
• 要创建和管理要素服务 webhook，您必须已被分配要素图层权限或被分配默认管理员角色或发布者角色。
• Webhook 接收器必须配置为通过 HTTPS 进行通信。 此处提供多个支持用作接收器的选项：例如第三方 Web 服务接收器（Microsoft Power Automate、Zapier 和 IFFT）和自定义 Web 服务。 有关如何创建自定义 Web 服务的示例或使用第三方接收器的入门指南，请参阅 Webhook 资料档案库。
• 要为要素服务配置 webhook，服务必须包含编辑功能，并且在不使用同步功能的情况下启用了更改追踪。
• 要为地理处理服务配置 webhook，服务必须为异步服务。

创建组织 webhook

您可通过组织 webhook 订阅至与 ArcGIS Enterprise 门户项目、群组和用户关联的事件的触发器。

注：

可以通过 ArcGIS Enterprise 门户网站或 ArcGIS Portal Directory 创建组织 webhook。 要查看创建围绕与用户、群组和项目相关的事件的 webhook 的示例 POST 请求，请参阅创建 webhook REST API 文档。

在 ArcGIS Portal Directory 中创建组织 webhook

要通过 ArcGIS Portal Directory 创建组织 webhook，请按照以下步骤操作：

1. 浏览至 ArcGIS Portal Directory，然后以具有管理员角色的用户身份登录。

   仅具有组织 webhook 权限的管理员或已分配默认管理员角色的成员可以创建和管理组织 webhook。

   https://organization.domain.com/context/sharing/rest
   

   登录后，随即显示帐户的用户资源页面。

2. 单击组织 ID 超链接，或按照以下格式发出请求，以访问门户自助资源页面：
   https://organization.domain.com/context/sharing/rest/portals/self
   

3. 滚动到自助资源页面的底部，然后单击Webhook > 创建 webhook 以访问创建 webhook 操作。
4. 访问创建 webhook 端点后，提供以下信息：
   1. 在名称文本框中，为 webhook 提供唯一名称。
   2. 在负载 URL 文本框中提供 webhook 接收器的负载 URL，创建 webhook 时会对其进行查询，以确保可以在接收器和 ArcGIS Enterprise 门户之间成功建立连接。

      示例负载 URL 如下所示：

      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow
      

   3. 或者，设置一个可用于对 webhook 与接收器的消息进行身份验证的 webhook 机密。 在机密（可选）文本框中，输入用户定义的字母数字字符串。
   4. 或者，在配置属性文本框中指定 webhook 的停用信息。

      默认情况下，如果在五天内发生了五次故障，则 webhook 会停用。

   5. 在您希望在哪些事件触发此 webhook 下，请选择允许我手动定义或向我发送所有内容。
      • 如果您选择允许我手动定义，请在向我发送这些以逗号分隔的事件的更改文本框中列出将用于此 webhook 的触发器事件。 例如，如果您想要订阅与组织中特定群组相关的所有事件，请输入与下方所示的一项相似的触发器事件，其中 [groupID] 表示与特定群组关联的唯一 ID：
        /groups/[groupID]/update
        

        要查看组织 webhook 所有支持的事件触发器的列表，请参阅事件触发器。
      • 如果您选择向我发送所有内容，将订阅所有受支持的触发器事件。 在每个事件发生时，您将收到通知。
5. 配置完上述参数后，单击创建 webhook 以提交请求。

   操作完成后，一个新的 webhook 将添加到您的组织。

在 ArcGIS Enterprise 门户网站中创建组织 webhook

要通过 ArcGIS Enterprise 门户网站创建组织 webhook，请按照以下步骤操作：

1. 确认您以默认管理员身份登录或具有组织 webhook 权限的自定义角色成员身份登录。
2. 浏览至组织 > 设置 > Webhook。
3. 单击创建 webhook。
4. 在创建 webhook 窗口中，执行以下操作：
   1. 在名称文本框中，为 webhook 提供唯一名称。
   2. 从类型下拉菜单中选择一种 webhook 类型。
      • 选择全部可订阅所有受支持的事件触发器。 在每个事件发生时，您将收到通知。
      • 选择项目、用户、群组或角色允许您手动定义要订阅的触发事件。
   3. 如果选择全部以外的 webhook 类型，则会出现一个与所选 webhook 类型相关的附加下拉菜单。 例如，如果您为 webhook 类型选择了项目，则会出现项目下拉菜单，允许您选择 webhook 将监控的特定项目。
   4. 从事件下拉菜单中选择触发事件。 例如，如果您希望在发布特定项目时调用 webhook，请选择 /items/<项目 ID>/publish。
   5. 在 Webhook URL 文本框中提供 webhook 接收器的负载 URL。 示例负载 URL 如下所示：
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow
      

   6. 或者，在 机密(可选)文本框中为 webhook 设置一个机密值。 机密值将包含在 webhook 有效负载中，并用于向接收器验证 webhook 消息。
5. 单击创建 webhook。

为组织 webhook 配置高级参数

应用于组织的 webhook 的高级设置允许您进一步自定义 webhook 的性能，例如指定传送尝试的次数、通知时间和传送尝试之间的时间。

注：

可以通过 ArcGIS Enterprise 门户网站或 ArcGIS Portal Directory 修改组织 webhook 的高级属性。 要查看配置这些高级属性的示例 POST 请求，请参阅更新 webhook 设置 REST API 文档。

在 ArcGIS Portal Directory 中配置高级参数

要通过 ArcGIS Portal Directory 设置高级属性，请执行以下操作：

1. 浏览至 ArcGIS Portal Directory，然后以具有管理员角色的用户身份登录。

   仅已分配有默认管理员角色的成员或分配有组织 webhook 权限的成员可以创建和管理组织 webhook。

   https://organization.domain.com/context/sharing/rest
   

   登录后，随即显示帐户的用户资源页面。

2. 单击组织 ID 超链接，或按照以下格式发出请求，以访问门户自助资源页面：
   https://organization.domain.com/context/sharing/rest/portals/self
   

3. 滚动到自助资源页面的底部，然后单击 Webhook > 设置 > 更新以访问更新 webhook 设置操作。
4. 访问更新 webhook 设置端点后，提供以下信息：
   1. 设置通知尝试次数的值。

      此值指定尝试传送 webhook 负载的次数。 默认情况下，ArcGIS Enterprise 门户将尝试传送负载三次。 尝试次数的值必须是 0 到 5 之间的整数。

   2. 设置以秒为单位的通知超时的值。

      此值以秒为单位指定时间长度，ArcGIS Enterprise 门户将在此时间内等待从接收器接收响应。 默认情况下，ArcGIS Enterprise 门户将等待 10 秒。 ArcGIS Enterprise 门户将等待的秒数值必须是 0 到 60 秒之内的整数。

   3. 设置以秒为单位的通知历时的值。

      此值指定每次负载传送尝试之间的时间量（以秒为单位）。 默认情况下，如果上次尝试失败，ArcGIS Enterprise 门户将在 5 秒后尝试传送另一个负载，直到达到通知尝试次数中指定的尝试次数为止。

5. 配置完上述参数后，单击更新 webhook 设置以提交请求。

   完成操作后，更新的属性将应用于每个已配置的组织 webhook。

在 ArcGIS Enterprise 门户网站中配置高级参数

要通过 ArcGIS Enterprise 门户网站设置高级属性，请执行以下操作：

1. 以默认管理员身份登录或具有组织 webhook 权限的自定义角色成员身份登录您的组织。
2. 单击站点顶部的组织，然后单击设置选项卡。
3. 单击页面左侧的 Webhook。
4. 单击高级 webhook 设置。
5. 在高级 webhook 设置窗口中，执行以下操作：
   1. 设置传送尝试次数的值。

      此值指定尝试传送 webhook 负载的次数。 默认情况下，ArcGIS Enterprise 门户将尝试传送负载三次。 尝试次数的值必须是 0 到 5 之间的整数。

   2. 设置通知超时的值。

      此值以秒为单位指定时间长度，ArcGIS Enterprise 门户将在此时间内等待从接收器接收响应。 默认情况下，ArcGIS Enterprise 门户将等待 10 秒。 ArcGIS Enterprise 门户将等待的秒数值必须是 0 到 60 秒之内的整数。

   3. 设置通知历时的值。

      此值指定每次负载传送尝试之间的时间量（以秒为单位）。 默认情况下，如果上次尝试失败，ArcGIS Enterprise 门户将在 5 秒后尝试传送另一个负载，直到达到传送尝试次数中指定的尝试次数为止。

6. 配置完上述设置后，单击保存。

   更新的属性将应用于每个已配置的组织 webhook。

创建地理处理服务 webhook

您可通过地理处理服务 webhook 订阅与地理处理服务关联的特定事件触发器。

注：

只能通过 ArcGIS Server Administrator Directory 创建地理处理服务 webhook。 要查看创建地理处理服务 webhook 的示例 POST 请求，请参阅 创建 webhookREST API 文档。

要为地理处理服务创建 webhook，请执行以下步骤：

1. 浏览至 ArcGIS Enterprise Administrator Site Directory，然后使用已分配合适的权限的成员身份登录。
   分配了地理处理权限的用户还需要在其自定义角色中添加发布基于服务器的图层权限。

   注：

   分配了地理处理权限的用户还需要在其自定义角色中添加发布基于服务器的图层权限。

   https://organization.domain.com/context/admin
   

2. 登录后，浏览至地理处理服务的 Webhook 资源，方法是单击服务 > [ServiceName] > Webhook > 创建，其中 [ServiceName] 表示将为之创建 webhook 的服务。 对于位于特定文件夹中的服务，单击服务 > [FolderName] > [ServiceName] > Webhook > 创建，其中 [FolderName] 表示服务所在的文件夹。

   警告：

   要为地理处理服务配置 webhook，地理处理服务必须为异步服务。

3. 访问创建 webhook 端点后，提供以下信息：
   1. 在名称文本框中，为 webhook 提供唯一名称。 提供的名称仅可包含字母数字值，因为使用特殊字符将导致错误消息。
   2. 或者，设置一个可用于对 webhook 与接收器的消息进行身份验证的 webhook 机密。 在签名密钥文本框中，输入用户定义的字母数字字符串。

      服务 Webhook 使用签名验证来确保从 ArcGIS Enterprise 发送到 Webhook 接收器的 Webhook 负载的完整性和安全性。 输入到签名密钥文本框的字母数字字符串被视为密钥，ArcGIS Enterprise 和 webhook 接收器都知道并独立存储该密钥。 当触发 Webhook 事件时，将使用 HMAC-SHA256 算法对密钥和负载进行哈希处理，从而创建签名。 然后签名作为 x-esriHook-Signature 标头值在 Webhook 请求中传递。 当 Webhook 有效负载传递到接收器时，接收器使用密钥和有效负载来创建自己的签名，该签名使用与 ArcGIS Enterprise 使用的相同的 HMAC-SHA256 算法。 如果请求标头中包含的签名与 Webhook 接收器创建的重新计算值匹配，则接收器可以信任 Webhook 有效负载。 否则，接收器可能会选择拒绝传入的 Webhook 负载。

   3. 在Hook URL 文本框中提供 webhook 接收器的负载 URL，创建 webhook 时会对其进行查询，以确保可以在接收器和部署的 ArcGIS Server 之间成功建立连接。 示例负载如下所示：
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow
      

   4. 或者，指定媒体类型。 在内容类型下拉菜单中，选择以下任一项：
      • application/json（默认）
      • application/x-www-form-urlencoded
   5. 或者，定义负载的格式。 在负载格式下拉菜单中，选择以下任一项：
      • JSON（默认）
      • PJSON
   6. 或者，使用激活参数在触发 webhook 时禁用或启用回调。 要启用，请选择 True。 要禁用，请选择 False。

      默认设置为启用回调。

4. 配置完上述参数后，单击创建以提交请求。

   操作完成后，新 webhook 将应用于特定的地理处理服务。

注：

与组织和要素服务 webhook 不同，地理处理服务 webhook 没有用户定义的事件触发器。 地理处理服务 webhook 会在地理处理作业完成后传送负载。 有关为地理处理服务传送的负载的详细信息，请参阅负载。

创建要素服务 webhook

您可通过要素服务 webhook 订阅与要素服务关联的特定事件触发器。

注：

只能通过 ArcGIS Server Administrator Directory 创建要素服务 webhook。 要查看创建要素服务 webhook 的示例 POST 请求，请参阅 创建 webhook REST API 文档。

要为要素服务创建 webhook，请执行以下步骤：

1. 浏览至 ArcGIS Enterprise Administrator Site Directory，然后使用已分配合适的权限的成员身份登录。
   仅分配有要素图层权限或默认管理员角色或发布者角色的成员才能创建和管理 webhook。
   https://organization.domain.com/context/admin
   

2. 登录后，浏览至要素服务的 Webhook 资源，方法是单击服务 > [ServiceName] > Webhook > 创建，其中 [ServiceName] 表示将为之创建 webhook 的服务。 对于位于特定文件夹中的服务，单击服务 > [FolderName] > [ServiceName] > Webhook > 创建，其中 [FolderName] 表示服务所在的文件夹。

   警告：

   要为要素服务配置 webhook，要素服务必须包含编辑功能，并且在不使用同步功能的情况下启用了更改追踪。

3. 访问创建 webhook 端点后，提供以下信息：
   1. 在名称文本框中，为 webhook 提供唯一名称。 提供的名称仅可包含字母数字值，因为使用特殊字符将导致错误消息。
   2. 在更改类型文本框中列出将用于此 webhook 的事件触发器。 例如，要在创建要素服务时调用 webhook，请使用以下事件触发器：

      示例

      FeaturesCreated
      

      要查看要素服务 webhook 支持的所有事件触发器的列表，请参阅事件触发器。
   3. 或者，设置一个可用于对 webhook 与接收器的消息进行身份验证的 webhook 机密。 在签名密钥文本框中，输入用户定义的字母数字字符串。

      服务 Webhook 使用签名验证来确保从 ArcGIS Enterprise 发送到 Webhook 接收器的 Webhook 负载的完整性和安全性。 输入到签名密钥文本框的字母数字字符串被视为密钥，ArcGIS Enterprise 和 webhook 接收器都知道并独立存储该密钥。 当触发 Webhook 事件时，将使用 HMAC-SHA256 算法对密钥和负载进行哈希处理，从而创建签名。 然后签名作为 x-esriHook-Signature 标头值在 Webhook 请求中传递。 当 Webhook 有效负载传递到接收器时，接收器使用密钥和有效负载来创建自己的签名，该签名使用与 ArcGIS Enterprise 使用的相同的 HMAC-SHA256 算法。 如果请求标头中包含的签名与 Webhook 接收器创建的重新计算值匹配，则接收器可以信任 Webhook 有效负载。 否则，接收器可能会选择拒绝传入的 Webhook 负载。

   4. 在Hook URL 文本框中提供 webhook 接收器的负载 URL，创建 webhook 时会对其进行查询，以确保可以在接收器和部署的 ArcGIS Server 之间成功建立连接。 示例负载如下所示：
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow
      

   5. 或者，指定媒体类型。 在内容类型下拉菜单中，选择以下任一项：
      • application/json（默认）
      • application/x-www-form-urlencoded
   6. 或者，定义负载的格式。 在负载格式下拉菜单中，选择以下任一项：
      • JSON（默认）
      • PJSON
   7. 或者，使用激活参数在触发 webhook 时禁用或启用回调。 要启用，请选择 True。 要禁用，请选择 False。

      默认设置为启用回调。

   8. 通过修改计划文本框中的秒信息，可以调整 webhook 的计划。 对于要频繁经历大量编辑的要素服务，降低秒值以在负载中接收包含较少事件信息的较频繁的 webhook。 对于不经历频繁更改的要素服务，请提高秒属性的值，以在负载中接收包含较多事件信息的较不频繁的 webhook。

      计划的最小值和默认值为 20 秒。

4. 配置完上述参数后，单击创建以提交请求。

   操作完成后，新 webhook 将应用于特定的要素服务。