SharePoint Webhook 概述Overview of SharePoint webhooks

借助 SharePoint Webhook,开发人员可以生成可订阅接收有关 SharePoint 中发生的特定事件通知的应用程序。SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. 事件被触发时,SharePoint 会向订阅服务器发送 HTTP POST 有效负载。When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. Webhook 的开发和使用相比 SharePoint 加载项远程事件接收器使用的 Windows Communication Foundation (WCF) 服务更加容易,因为 Webhook 是常规的 HTTP 服务 (Web API)。Webhooks are easier to develop and consume than Windows Communication Foundation (WCF) services used by SharePoint Add-in remote event receivers because webhooks are regular HTTP services (web API).

当前 Webhook 仅针对 SharePoint 列表项启用。Currently webhooks are only enabled for SharePoint list items. SharePoint 列表项 Webhook 覆盖对应于指定 SharePoint 列表或文档库的列表项更改的事件。SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint Webhook 提供一个简单的通知管道,以便你的应用程序得以了解对 SharePoint 列表的更改,而无需轮询服务。SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. 有关详细信息,请参阅 SharePoint 列表 WebhookFor more information, see SharePoint list webhooks.

创建 webhookCreating webhooks

若要创建新的 SharePoint webhook,请将新的订阅添加到特定 SharePoint 资源,如 SharePoint 列表。To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list.

创建新的订阅需要以下信息:The following information is required for creating a new subscription:

  • 资源。为其创建订阅的资源终结点 URL。例如 SharePoint 列表 API URL。Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
  • 服务器通知 URLServer notification URL. 服务终结点 URL。Your service endpoint URL. 事件在指定资源中发生时,SharePoint 将 HTTP POST 发送到此终结点。SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource.
  • 到期日期Expiration date. 订阅的到期日期。The expiration date for your subscription. 到期日期不应超过 180 天。The expiration date should not be more than 180 days. 默认情况下,订阅被设为自创建之日起 180 天后到期。By default, subscriptions are set to expire 180 days from when they are created.

如果需要,还可以包括以下信息:You can also include the following information if needed:

  • 客户端状态Client State. 传递回所有通知上的客户端的一个不透明字符串。An opaque string passed back to the client on all notifications. 可以使用此信息对通知进行验证、标记不同的订阅或其他原因。You can use this for validating notifications, tagging different subscriptions, or other reasons.

处理 Webhook 验证请求Handling webhook validation requests

创建新的订阅时,SharePoint 将验证通知 URL 是否支持接收 Webhook 通知。When a new subscription is created, SharePoint validates whether the notification URL supports receiving webhook notifications. 订阅创建请求期间将执行此验证。This validation is performed during the subscription creation request. 只有在服务及时响应并返回验证令牌时,才会创建该订阅。The subscription is only created if your service responds in a timely manner back with the validation token.

示例验证请求Example validation request

创建新的订阅时,SharePoint 将以类似于以下示例的格式,将 HTTP POST 请求发送到注册的 URL:When a new subscription is created, SharePoint sends an HTTP POST request to the registered URL in a format similar to the following example:

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

响应Response

若要成功创建订阅,服务必须通过返回 validationToken 查询字符串参数的值以纯文本格式的响应对请求作出响应。For the subscription to be created successfully, your service must respond to the request by returning the value of the validationtoken query string parameter as a plain-text response.

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

{randomString}

如果应用程序返回了一个状态代码而不是 200,或无法使用 validationToken 参数值做出响应,则创建新订阅的请求会失败。If your application returns a status code other than 200, or fails to respond with the value of the validationtoken parameter, the request to create a new subscription fails.

接收通知Receiving notifications

通知有效负载将告知应用程序有关指定订阅的指定资源中发生的事件。The notification payload informs your application that an event occurred in a given resource for a given subscription. 如果同一时间段内对资源进行多处更改,应用程序的多个通知可能会分批放到单个请求中。Multiple notifications to your application may be batched together into a single request if multiple changes occurred in the resource within the same time period.

如果在创建订阅时使用通知有效负载正文,它还将包含客户端状态。The notification payload body also contains your client state if you used it when creating the subscription.

Webhook 通知资源Webhook notification resource

当 SharePoint webhook 通知请求提交到已注册的通知 URL 时,通知资源将定义提供给服务的数据形状。The notification resource defines the shape of the data provided to your service when a SharePoint webhook notification request is submitted to your registered notification URL.

JSON 表示形式JSON representation

此服务生成的所有通知都被序列化为 webhookNotification 实例:Each notification generated by the service is serialized into a webhookNotification instance:

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

由于多个通知可能被提交到单个请求中的服务,它们会一起组合在一个具有单个数组的对象中:Because multiple notifications may be submitted to your service in a single request, these are combined together in an object with a single array value:

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

属性Properties

属性名称Property name 类型Type 说明Description
resourceresource 字符串String 注册订阅的列表的唯一标识符。Unique identifier of the list where the subscription is registered.
subscriptionIdsubscriptionId StringString subscription 资源的唯一标识符。The unique identifier for the subscription resource.
clientStateclientState 字符串 - 可选String - optional 此订阅的通知消息中回传的An optional string value that is passed back in the notification. 可选字符串值。message for this subscription.
expirationDateTimeexpirationDateTime 日期/时间DateTime 如果没有更新或续订,订阅将过期的日期和时间。The date and time when the subscription expires if not updated or renewed.
tenantIdtenantId 字符串String 生成此通知的租户的唯一标识符。Unique identifier for the tenant that generated this notification.
siteUrlsiteUrl 字符串String 注册订阅的网站的服务器相对 URL。Server relative URL of the site where the subscription is registered.
webIdwebId 字符串String 注册订阅的 Web 的唯一标识符。Unique identifier of the web where the subscription is registered.

示例通知Example notification

对服务通知 URL 的 HTTP 请求的正文包含一个 Webhook 通知。The body of the HTTP request to your service notification URL contains a webhook notification. 以下示例显示具有一个通知的有效负载:The following example shows a payload with one notification:

{
   "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,以在通知应用程序时查询更改日志中的更改集合,并存储更改令牌值用于任何后续调用。The notification doesn't include any information about the changes that triggered it. Your application is expected to use the GetChanges API on the list to query the collection of changes from the change log and store the change token value for any subsequent calls when the application is notified.

事件类型Event types

SharePoint webhook 仅支持异步事件。这意味着在发生更改后才触发 webhook(类似于 -ed 事件),因此不可能同步(-ing 事件)。SharePoint webhooks only support asynchronous events. This means that webhooks are only fired after a change happened (similar to -ed events), and thus synchronous (-ing events) are not possible.

错误处理Error handling

如果将通知发送到应用程序时出错,SharePoint 最多会重试 5 次来传递通知。If an error occurs while sending the notification to your application, SharePoint retries up to 5 times to deliver the notification. HTTP 状态代码在 200-299 范围外的任何响应或超时响应都会在 5 分钟后再次尝试。Any response with an HTTP status code outside of the 200-299 range, or that times out, is attempted again 5 minutes later. 如果在 5 次尝试后请求均未成功,将会删除通知。If the request is not successful after 5 attempts, the notification is dropped. 今后若有通知,仍会尝试发送到应用。Future notifications will still be attempted to your application.

到期Expiration

默认情况下,如果未指定 expirationDateTime 值,webhook 订阅将被设置为 180 天后过期。Webhook subscriptions are set to expire after 180 days by default if an expirationDateTime value is not specified.

创建订阅时需要设置到期日期。到期日期不应超过 180 天。应用程序应根据应用程序的需要,通过定期更新订阅来处理到期日期。You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically.

重试机制Retry mechanism

如果事件发生在 SharePoint 中并且服务终结点不可访问(例如,出于维护原因),SharePoint 将重试发送通知。If an event occurs in SharePoint and your service endpoint is not reachable (for example, due to maintenance) SharePoint retries sending the notification. SharePoint 会重试 5 次,每次尝试间隔等待 5 分钟SharePoint performs a retry of 5 times with a 5-minute wait time between the attempts. 如果由于某种原因服务停用时间较长,那么下一次在它处于活动状态并通过 SharePoint 调用时,对 GetChanges() 的调用将恢复服务不可用时遗漏的更改。If for some reason your service is down for a longer time, the next time it's up and gets called by SharePoint, the call to the GetChanges() recovers the changes that were missed when your service was not available.