SharePoint Webhook 概述

项目
04/08/2023

借助 SharePoint Webhook，开发人员可以生成可订阅接收有关 SharePoint 中发生的特定事件通知的应用程序。事件被触发时，SharePoint 会向订阅服务器发送 HTTP POST 有效负载。 Webhook 的开发和使用相比 SharePoint 加载项远程事件接收器使用的 Windows Communication Foundation (WCF) 服务更加容易，因为 Webhook 是常规的 HTTP 服务 (Web API)。

当前 Webhook 仅针对 SharePoint 列表项启用。 SharePoint 列表项 Webhook 覆盖对应于指定 SharePoint 列表或文档库的列表项更改的事件。 SharePoint Webhook 提供一个简单的通知管道，以便你的应用程序得以了解对 SharePoint 列表的更改，而无需轮询服务。有关详细信息，请参阅 SharePoint 列表 Webhook。

创建 webhook

若要创建新的 SharePoint webhook，请将新的订阅添加到特定 SharePoint 资源，如 SharePoint 列表。

创建新的订阅需要以下信息：

资源。要为其创建订阅的资源终结点 URL。例如，SharePoint 列表 API URL。
服务器通知 URL。服务终结点 URL。事件在指定资源中发生时，SharePoint 将 HTTP POST 发送到此终结点。
到期日期。订阅的到期日期。到期日期不应超过 180 天。默认情况下，订阅被设为自创建之日起 180 天后到期。

如果需要，还可以包括以下信息：

客户端状态。传递回所有通知上的客户端的一个不透明字符串。可以使用此信息对通知进行验证、标记不同的订阅或其他原因。

处理 Webhook 验证请求

创建新的订阅时，SharePoint 将验证通知 URL 是否支持接收 Webhook 通知。订阅创建请求期间将执行此验证。只有在服务及时响应并返回验证令牌时，才会创建该订阅。

示例验证请求

创建新的订阅时，SharePoint 将以类似于以下示例的格式，将 HTTP POST 请求发送到注册的 URL：

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

响应

若要成功创建订阅，服务必须通过返回 validationToken 查询字符串参数的值以纯文本格式的响应对请求作出响应。

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

如果应用程序返回了一个状态代码而不是 200，或无法使用 validationToken 参数值做出响应，则创建新订阅的请求会失败。

接收通知

通知有效负载将告知应用程序有关指定订阅的指定资源中发生的事件。如果同一时间段内对资源进行多处更改，应用程序的多个通知可能会分批放到单个请求中。

如果在创建订阅时使用通知有效负载正文，它还将包含客户端状态。

Webhook 通知资源

当 SharePoint webhook 通知请求提交到已注册的通知 URL 时，通知资源将定义提供给服务的数据形状。

JSON 表示形式

此服务生成的所有通知都被序列化为 webhookNotification 实例：

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

由于多个通知可能被提交到单个请求中的服务，它们会一起组合在一个具有单个数组值的对象中：

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

属性

属性名称	类型	说明
resource	字符串	注册订阅的列表的唯一标识符。
subscriptionId	String	subscription 资源的唯一标识符。
clientState	字符串 - 可选	此订阅的通知消息中回传的可选字符串值。
expirationDateTime	日期/时间	如果没有更新或续订，订阅将过期的日期和时间。
tenantId	字符串	生成此通知的租户的唯一标识符。
siteUrl	字符串	注册订阅的网站的服务器相对 URL。
webId	字符串	注册订阅的 Web 的唯一标识符。

示例通知

对服务通知 URL 的 HTTP 请求的正文包含一个 Webhook 通知。以下示例显示具有一个通知的有效负载：

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

通知并不包括任何有关触发它的更改的信息。应用程序应使用列表上的 GetChanges API，以在通知应用程序时查询更改日志中的更改集合，并存储更改令牌值用于任何后续调用。

事件类型

SharePoint webhook 仅支持异步事件。这意味着在发生更改后才触发 webhook（类似于 -ed 事件），因此不可能同步（-ing 事件）。

错误处理

如果将通知发送到应用程序时出错，SharePoint 最多会重试 5 次来传递通知。 HTTP 状态代码在 200-299 范围外的任何响应或超时响应都会在 5 分钟后再次尝试。如果在 5 次尝试后请求均未成功，将会删除通知。今后若有通知，仍会尝试发送到应用。

到期

默认情况下，如果未指定 expirationDateTime 值，webhook 订阅将被设置为 180 天后过期。

创建订阅时需要设置到期日期。到期日期应小于 180 天。应用程序需要根据应用程序需要，通过定期更新订阅来处理到期日期。

重试机制

如果事件发生在 SharePoint 中并且服务终结点不可访问（例如，出于维护原因），SharePoint 将重试发送通知。 SharePoint 会重试 5 次，每次尝试间隔等待 5 分钟。如果由于某种原因服务停用时间较长，那么下一次在它处于活动状态并通过 SharePoint 调用时，对 GetChanges() 的调用将恢复服务不可用时遗漏的更改。