Обзор веб-перехватчиков SharePointOverview of SharePoint webhooks

Используя веб-перехватчики SharePoint, разработчики могут создавать приложения, которые подписываются на уведомления о событиях, происходящих в 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. Веб-перехватчики легче разрабатывать и задействовать, чем службы Windows Communication Foundation (WCF), используемые удаленными приемниками событий в надстройках SharePoint, так как веб-перехватчики представляют собой обычные HTTP-службы (веб-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).

В настоящее время веб-перехватчики поддерживаются только для элементов списков SharePoint.Currently webhooks are only enabled for SharePoint list items. Веб-перехватчики SharePoint обрабатывают события, связанные с изменением элементов списка или библиотеки документов SharePoint.SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. Веб-перехватчики SharePoint предоставляют простой канал уведомлений, чтобы приложение узнавало об изменениях списка 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.For more information, see SharePoint list webhooks.

Создание веб-перехватчиковCreating webhooks

Чтобы создать веб-перехватчик SharePoint, необходимо добавить подписку на определенный ресурс 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-адрес конечной точки ресурса, для которого создается подписка. Например, это может быть URL-адрес API списка SharePoint. Resource. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL.
  • Серверный URL-адрес уведомлений.Server 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.

Обработка запросов на проверку веб-перехватчиковHandling webhook validation requests

При создании подписки SharePoint проверяет, поддерживает ли указанный URL-адрес получение уведомлений веб-перехватчиков.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 notification resource

В ресурсе уведомлений определяется форма данных, предоставляемых службе при отправке запроса уведомления веб-перехватчика SharePoint на зарегистрированный 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.

Представление JSONJSON 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"
}

Так как в одном запросе службе может отправляться несколько уведомлений, они объединяются в объект с одним массивом value: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 StringString Уникальный идентификатор списка, в котором зарегистрирована подписка.Unique identifier of the list where the subscription is registered.
subscriptionIdsubscriptionId СтрокаString Уникальный идентификатор ресурса подписки.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 DateTimeDateTime Дата и время окончания срока действия подписки, если она не будет обновлена или возобновлена.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 StringString Относительный (от сервера) URL-адрес сайта, на котором зарегистрирована подписка.Server relative URL of the site where the subscription is registered.
webIdwebId StringString Уникальный идентификатор сети, в которой зарегистрирована подписка.Unique identifier of the web where the subscription is registered.

Пример уведомленияExample notification

Текст HTTP-запроса на URL-адрес уведомлений службы содержит уведомление веб-перехватчика.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"
      }
   ]
}

Уведомление не включает сведения о вызвавших его изменениях. Ожидается, что при получении уведомления приложение будет использовать для списка API GetChanges, чтобы запросить коллекцию изменений из журнала изменений и сохранить значение маркера изменений для последующих вызовов.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 поддерживают только асинхронные события. Это означает, что веб-перехватчики вызываются только после изменения (подобно событиям -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

По умолчанию срок действия подписок на веб-перехватчики истекает спустя 180 дней, если не указано значение expirationDateTime.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.