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

Статья
04/08/2023

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

В настоящее время веб-перехватчики поддерживаются только для элементов списков SharePoint. Веб-перехватчики SharePoint обрабатывают события, связанные с изменением элементов списка или библиотеки документов SharePoint. Веб-перехватчики SharePoint предоставляют простой канал уведомлений, чтобы приложение узнавало об изменениях списка SharePoint, не выполняя опрос службы. Дополнительные сведения см. в статье Веб-перехватчики для списков SharePoint.

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

Чтобы создать веб-перехватчик SharePoint, необходимо добавить подписку на определенный ресурс SharePoint, например список SharePoint.

Для создания подписки необходимы следующие сведения:

Ресурс. URL-адрес конечной точки ресурса, для которых создается подписка. Например, URL-адрес API списка SharePoint.
Серверный URL-адрес уведомлений. URL-адрес конечной точки службы. SharePoint отправляет запрос HTTP POST в эту конечную точку, когда в указанном ресурсе происходят события.
Срок действия. Дата окончания срока действия подписки. Срок действия не должен превышать 180 дней. По умолчанию срок действия подписки истекает через 180 дней после ее создания.

При необходимости вы также можете указать следующие сведения:

Состояние клиента. Непрозрачная строка, которая передается клиенту со всеми уведомлениями. Ее можно использовать для проверки уведомлений, добавления тегов к подпискам и других целей.

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

При создании подписки SharePoint проверяет, поддерживает ли указанный URL-адрес получение уведомлений веб-перехватчиков. Эта проверка выполняется при запросе на создание подписки. Подписка будет создана, только если служба своевременно отправит ответ с маркером проверки.

Пример запроса на проверку

При создании подписки 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, запрос на создание подписки не выполняется.

Получение уведомлений

Полезные данные уведомления сообщают приложению, что в определенном ресурсе для той или иной подписки произошло событие. Несколько уведомлений для приложения могут быть объединены в один запрос, если за один период времени в ресурсе произошло несколько событий.

Кроме того, полезные данные уведомления содержат состояние клиента, если он использовался при создании подписки.

Ресурс уведомлений веб-перехватчиков

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

{
   "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	String	Уникальный идентификатор списка, в котором зарегистрирована подписка.
subscriptionId	Строка	Уникальный идентификатор ресурса подписки.
clientState	Строка (необязательный)	Необязательное строковое значение, возвращаемое в уведомлении для подписки.
expirationDateTime	DateTime	Дата и время окончания срока действия подписки, если она не будет обновлена или возобновлена.
tenantId	Строка	Уникальный идентификатор клиента, создавшего это уведомление.
siteUrl	String	Относительный (от сервера) URL-адрес сайта, на котором зарегистрирована подписка.
webId	String	Уникальный идентификатор сети, в которой зарегистрирована подписка.

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

Текст HTTP-запроса на URL-адрес уведомлений службы содержит уведомление веб-перехватчика. В следующем примере показаны полезные данные одного уведомления:

{
   "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, чтобы запросить коллекцию изменений из журнала изменений и сохранить значение маркера изменений для последующих вызовов.

Типы событий

Веб-перехватчики SharePoint поддерживают только асинхронные события. Это означает, что веб-перехватчики вызываются только после изменения (подобно событиям -ed), поэтому использовать синхронные события (-ing) невозможно.

Обработка ошибок

Если при отправке уведомления приложению возникает ошибка, SharePoint пытается доставить его еще 5 раз. Любой ответ с кодом состояния HTTP, который не находится в диапазоне 200–299, или с истекшим временем ожидания выполняется повторно через 5 минут. Если все 5 попыток выполнить запрос ни к чему не привели, уведомление удаляется. В дальнейшем попытки доставить уведомления приложению будут повторяться.

Срок действия

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

При создании подписки необходимо указать дату окончания срока действия. Срок действия должен быть менее 180 дней. Ожидается, что приложение будет обрабатывать дату окончания срока действия в соответствии со своими потребностями, периодически обновляя подписку.

Механизм повтора

Если в SharePoint происходит событие, а конечная точка службы недоступна (например, во время технического обслуживания), SharePoint пытается отправить уведомление еще раз. SharePoint повторяет попытку 5 раз с 5-минутными интервалами. Если по той или иной причине служба недоступна дольше этого времени, то при следующем включении и вызове от SharePoint вызов метода GetChanges() восстанавливает пропущенные изменения.

Поделиться через