【SharePoint 】SharePoint Web挂钩概述

SharePoint webhooks使开发人员能够构建订阅接收SharePoint中发生的特定事件通知的应用程序。当事件被触发时，SharePoint会向订阅者发送HTTP POST有效负载。与SharePoint插件远程事件接收器使用的Windows Communication Foundation（WCF）服务相比，Webhook更易于开发和使用，因为Webhook是常规HTTP服务（web API）。

目前，Webhook仅对SharePoint列表项启用。SharePoint列表项挂钩涵盖了与给定SharePoint列表或文档库的列表项更改相对应的事件。SharePoint webhooks提供了一个简单的通知管道，这样您的应用程序就可以在不轮询服务的情况下知道SharePoint列表的更改。有关详细信息，请参阅SharePoint列表webhooks。

创建webhooks

要创建新的SharePoint webhook，您需要向特定的SharePoint资源（如SharePoint列表）添加新的订阅。

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

• 资源。您正在为其创建订阅的资源终结点URL。例如，SharePoint列表API URL。
• 服务器通知URL。您的服务端点URL。当指定资源中发生事件时，SharePoint会向此端点发送HTTP POST。
• 到期日期。订阅的到期日期。有效期不应超过180天。默认情况下，订阅设置为创建后180天到期。
  如果需要，您还可以包含以下信息：
• 客户状态。在所有通知上传递回客户端的不透明字符串。您可以使用它来验证通知、标记不同的订阅或其他原因。
   

处理webhook验证请求

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

验证请求示例

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

超文本传输协议

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实例：

JSON

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

因为在一个请求中可能会向您的服务提交多个通知，所以这些通知会组合在一个具有单个数组值的对象中：

JSON

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

通知示例

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

JSON

{
  "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 webhooks仅支持异步事件。这意味着只有在发生更改后才会触发Webhook（类似于-ed事件），因此不可能实现同步（-ing事件）。

错误处理

如果在向您的应用程序发送通知时发生错误，SharePoint将重试最多5次以传递通知。任何HTTP状态代码超出200-299范围或超时的响应都会在5分钟后再次尝试。如果请求在5次尝试后未成功，则通知将被丢弃。未来仍将尝试向您的应用程序发送通知。

到期

如果未指定expirationDateTime值，默认情况下，Webhook订阅将在180天后过期。

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

重试机制

如果SharePoint中发生事件，并且您的服务端点无法访问（例如，由于维护），SharePoint将重试发送通知。SharePoint执行5次重试，两次尝试之间有5分钟的等待时间。如果由于某种原因，您的服务停机时间较长，下次它启动并被SharePoint调用时，对GetChanges（）的调用将恢复您的服务不可用时错过的更改。