Начало работы с веб-перехватчиками SharePoint

  • Статья

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

Мы будем использовать простые HTTP-запросы, чтобы вам было легче понять принцип работы веб-перехватчиков.

Чтобы выполнить представленные в этой статье пошаговые инструкции, скачайте и установите следующие средства:

Шаг 1. Регистрация приложения Azure AD для клиента Postman

Чтобы клиент Postman мог взаимодействовать с SharePoint, необходимо зарегистрировать приложение Microsoft Azure Active Directory (Azure AD) в клиенте Azure AD, связанном с клиентом Office 365.

  1. Зарегистрируйте приложение как Веб-приложение.

  2. Для доступа к SharePoint Online важно предоставить приложению Azure AD разрешения на доступ к приложению Office 365 SharePoint Online и выбрать разрешение Чтение и запись элементов и списков во всех семействах веб-сайтов.

    Примечание.

    Дополнительные сведения о добавлении приложения Azure AD и предоставлении разрешений приложениям см. в разделе Добавление приложения.

  3. Введите указанную ниже конечную точку в качестве URL-адреса ответа (перенаправления) для приложения. Это конечная точка, в которую Azure AD отправляет ответ проверки подлинности, включая маркер доступа, если проверка подлинности прошла успешно.

    https://www.getpostman.com/oauth2/callback

  4. Создайте Ключ, который будет секретом клиента.

  5. Указанные ниже свойства пригодятся вам позже, поэтому скопируйте их в безопасное место.

    • Идентификатор клиента
    • Client Secret

Шаг 2. Создание приемника веб-перехватчиков

Чтобы создать для этого проекта приемник веб-перехватчиков, используйте проект веб-API Visual Studio.

Создание проекта веб-API ASP.NET

  1. Откройте Visual Studio.
  2. Выберите Файл>Создать>Проект.
  3. В области Шаблоны выберите Установленные шаблоны и разверните узел Visual C#.
  4. В разделе Visual C# выберите Интернет.
  5. В списке шаблонов проектов выберите Веб-приложение ASP.NET.
  6. Назовите проект SPWebhooksReceiver и нажмите кнопку ОК.
  7. В диалоговом окне Новый проект ASP.NET выберите шаблон Веб-API в группе ASP.NET 4.5.
  8. Нажмите кнопку Изменить способ проверки подлинности и выберите Без проверки подлинности.
  9. Нажмите кнопку ОК, чтобы создать проект веб-API.

Примечание.

Вы можете снять флажок Разместить в облаке, так как этот проект не будет развертываться в облаке.

Visual Studio создаст ваш проект.

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

Установка пакетов Nuget

Для ведения журнала запросов, поступающих от SharePoint, используется трассировка веб-API ASP.NET. Чтобы установить пакет трассировки, сделайте следующее:

  1. Откройте обозреватель решений в Visual Studio.
  2. Откройте контекстное меню проекта и выберите Управление пакетами NuGet.
  3. В поле поиска введите Microsoft.AspNet.WebApi.Tracing.
  4. В результатах поиска выберите пакет Microsoft.AspNet.WebApi.Tracing и нажмите кнопку Установить, чтобы установить пакет.

Сборка модели SPWebhookNotification

Каждое уведомление, созданное службой, сериализуется в экземпляр webhookNotification. Вам нужно создать простую модель, которая представляет этот экземпляр уведомления.

  1. Откройте обозреватель решений в Visual Studio.

  2. Откройте контекстное меню папки Модели и выберите Добавить>Класс.

  3. Введите имя класса SPWebhookNotification и нажмите кнопку Добавить, чтобы добавить класс в проект.

  4. Добавьте следующий код в текст класса SPWebhookNotification:

    public string SubscriptionId { get; set; }
public string ClientState { get; set; }
public string ExpirationDateTime { get; set; }
public string Resource { get; set; }
public string TenantId { get; set; }
public string SiteUrl { get; set; }
public string WebId { get; set; }

Сборка модели SPWebhookContent

Так как в одном запросе приемнику веб-перехватчиков могут отправляться несколько уведомлений, они объединяются в объект со значением единого массива. Создайте простую модель, представляющую массив.

  1. Откройте обозреватель решений в Visual Studio.

  2. Откройте контекстное меню папки Модели и выберите Добавить>Класс.

  3. Введите имя класса SPWebhookContent и нажмите кнопку Добавить, чтобы добавить класс в проект.

  4. Добавьте следующий код в текст класса SPWebhookContent:

      public List<SPWebhookNotification> Value { get; set; }

Добавление состояния клиента веб-перехватчиков SharePoint

Веб-перехватчики позволяют использовать необязательное строковое значение, возвращаемое в уведомлении для подписки. С его помощью можно проверить, действительно ли запрос поступает из доверенного источника (в данном случае — SharePoint).

Добавьте значение состояния клиента, с помощью которого приложение может проверять входящие запросы.

  1. Откройте обозреватель решений в Visual Studio.

  2. Откройте файл web.config и добавьте следующий ключ состояния клиента в раздел <appSettings>:

    <add key="webhookclientstate" value="A0A354EC-97D4-4D83-9DDB-144077ADB449"/>

Включение трассировки

Включите трассировку в файле web.config, добавив следующий код в элемент <system.web> в разделе <configuration>:

<trace enabled="true"/>

Вам потребуется средство записи трассировки, поэтому его следует добавить в конфигурацию контроллера (в данном случае используйте конфигурацию из System.Diagnostics).

  1. Откройте обозреватель решений в Visual Studio.

  2. Откройте файл WebApiConfig.cs в папке App_Start.

  3. Добавьте следующую строку в метод Register:

    config.EnableSystemDiagnosticsTracing();

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

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

  1. Откройте обозреватель решений в Visual Studio.

  2. Откройте контекстное меню папки Контроллеры и выберите Добавить>Контроллер.

  3. В диалоговом окне Добавление шаблона выберите Контроллер Web API 2 – пустой.

  4. Нажмите кнопку Добавить.

  5. Назовите контроллер SPWebhookController и нажмите кнопку Добавить, чтобы добавить контроллер API в проект.

  6. Замените операторы using следующим кодом:

    using Newtonsoft.Json;
using SPWebhooksReceiver.Models;
using System.Collections.Generic;
using System.Configuration;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using System.Web;
using System.Web.Http;
using System.Web.Http.Tracing;

  7. Замените код класса SPWebhookController следующим кодом:

    [HttpPost]
public HttpResponseMessage HandleRequest()
{
    HttpResponseMessage httpResponse = new HttpResponseMessage(HttpStatusCode.BadRequest);
    var traceWriter = Configuration.Services.GetTraceWriter();
    string validationToken = string.Empty;
    IEnumerable<string> clientStateHeader = new List<string>();
    string webhookClientState = ConfigurationManager.AppSettings["webhookclientstate"].ToString();

    if (Request.Headers.TryGetValues("ClientState", out clientStateHeader))
    {
        string clientStateHeaderValue = clientStateHeader.FirstOrDefault() ?? string.Empty;

        if (!string.IsNullOrEmpty(clientStateHeaderValue) && clientStateHeaderValue.Equals(webhookClientState))
        {
            traceWriter.Trace(Request, "SPWebhooks",
                TraceLevel.Info,
                string.Format("Received client state: {0}", clientStateHeaderValue));

            var queryStringParams = HttpUtility.ParseQueryString(Request.RequestUri.Query);

            if (queryStringParams.AllKeys.Contains("validationtoken"))
            {
                httpResponse = new HttpResponseMessage(HttpStatusCode.OK);
                validationToken = queryStringParams.GetValues("validationtoken")[0].ToString();
                httpResponse.Content = new StringContent(validationToken);

                traceWriter.Trace(Request, "SPWebhooks",
                    TraceLevel.Info,
                    string.Format("Received validation token: {0}", validationToken));
                return httpResponse;
            }
            else
            {
                var requestContent = Request.Content.ReadAsStringAsync().Result;

                if (!string.IsNullOrEmpty(requestContent))
                {
                    SPWebhookNotification notification = null;

                    try
                    {
                        var objNotification = JsonConvert.DeserializeObject<SPWebhookContent>(requestContent);
                        notification = objNotification.Value[0];
                    }
                    catch (JsonException ex)
                    {
                        traceWriter.Trace(Request, "SPWebhooks",
                            TraceLevel.Error,
                            string.Format("JSON deserialization error: {0}", ex.InnerException));
                        return httpResponse;
                    }

                    if (notification != null)
                    {
                        Task.Factory.StartNew(() =>
                        {
                              //handle the notification here
                              //you can send this to an Azure queue to be processed later
                            //for this sample, we just log to the trace

                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("Resource: {0}", notification.Resource));
                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("SubscriptionId: {0}", notification.SubscriptionId));
                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("TenantId: {0}", notification.TenantId));
                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("SiteUrl: {0}", notification.SiteUrl));
                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("WebId: {0}", notification.WebId));
                            traceWriter.Trace(Request, "SPWebhook Notification",
                                TraceLevel.Info, string.Format("ExpirationDateTime: {0}", notification.ExpirationDateTime));

                        });

                        httpResponse = new HttpResponseMessage(HttpStatusCode.OK);
                    }
                }
            }
        }
        else
        {
            httpResponse = new HttpResponseMessage(HttpStatusCode.Forbidden);
        }
    }

    return httpResponse;
}

  8. Сохраните файл.

Шаг 3. Отладка приемника веб-перехватчиков

  1. Нажмите клавишу F5 для отладки приемника веб-перехватчиков.
  2. Скопируйте номер порта из адресной строки браузера. Пример: http://localhost:<_port-number_>

Шаг 4. Запуск прокси-сервера ngrok

  1. Откройте терминал консоли.

  2. Перейдите к папке, в которую вы распаковали ngrok.

  3. Чтобы запустить ngrok, введите следующую команду с номером порта, скопированным на предыдущем шаге:

    ./ngrok http port-number --host-header=localhost:port-number

    Должен запуститься ngrok.

  4. Скопируйте HTTPS-адрес переадресации. Это адрес будет использоваться в качестве прокси службы для отправки запросов из SharePoint.

Шаг 5. Добавление подписки на веб-перехватчик с помощью Postman

Получение нового маркера доступа

Postman значительно упрощает работу с API. Для начала настройте аутентификацию Postman с помощью Azure AD, чтобы отправлять запросы API в SharePoint. Вы будете использовать приложение Azure AD, зарегистрированное на шаге 1.

  1. Откройте Postman. Вы увидите боковую панель и редактор запросов.

  2. Выберите вкладку Authorization (Авторизация) в редакторе запросов.

  3. Выберите OAuth 2.0 в списке Type (Тип).

  4. Нажмите кнопку Get New Access Token (Получить новый маркер доступа).

  5. В диалоговом окне введите следующее:

    • Auth URL:
      • https://login.microsoftonline.com/common/oauth2/authorize?resource=https%3A%2F%2F<_your-sharepoint-tenant-url-without-https_>
      • замените your-sharepoint-tenant-url-without-https URL-адресом клиента без префикса https.
    • Access Token URL: https://login.microsoftonline.com/common/oauth2/token
    • Client Id: идентификатор клиента для приложения, зарегистрированного на шаге 1.
    • Client Secret: секрет клиента для приложения, зарегистрированного на шаге 1.
    • Token name: sp_webhooks_token
    • Grant type: Authorization Code

  6. Нажмите Request Token (Запросить маркер), чтобы войти, предоставить разрешения и получить маркер для сеанса.

  7. При успешном получении маркера на вкладку Авторизация должна появиться access_token переменная.

  8. Нажмите Add token to header (Добавить маркер к заголовку).

  9. Дважды щелкните переменную access_token , чтобы добавить маркер в заголовок запроса.

    Получение нового маркера доступа в Postman

Получение идентификатора списка документов

Вам необходимо управлять веб-перехватчиками для стандартной библиотеки документов Документы, подготовленной в семействе веб-сайтов по умолчанию. Чтобы получить идентификатор этого списка, отправьте запрос GET:

  1. Введите следующий URL-адрес запроса:

    https://site-collection/_api/web/lists/getbytitle('Documents')?$select=Title,Id

  2. Замените site-collection именем своего семейства веб-сайтов.

    Postman выполнит запрос. В случае успешного выполнения появится результат.

  3. Скопируйте значение Id из результатов. Это значение Id потребуется позже для отправки запросов к веб-перехватчикам.

Добавление подписки на веб-перехватчик

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

  1. Замените запрос GET на запрос POST.

  2. Введите следующий URL-адрес запроса:

    https://site-collection/_api/web/lists('list-id')/subscriptions

  3. Замените site-collection на имя вашего семейства веб-сайтов.

  4. Перейдите на вкладку Headers (Запросы).

  5. Убедитесь, что у вас по-прежнему есть заголовок Authorization. В противном случае необходимо запросить новый маркер доступа.

  6. Добавьте следующие пары ключ>значение для заголовка:

    • Принять: application/json;odata=nometadata
    • Тип содержимого: application/json

  7. Перейдите на вкладку Body (Текст) и выберите формат raw.

  8. Вставьте в качестве текста следующий код JSON:

    {
  "resource": "https://site-collection/_api/web/lists('list-id')",
  "notificationUrl": "https://ngrok-forwarding-address/api/spwebhook/handlerequest",
  "expirationDateTime": "2016-10-27T16:17:57+00:00",
  "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449"
}

    Добавление текста веб-перехватчика в Postman

  9. Убедитесь, что значение expirationDateTime превышает текущую дату не более чем на 6 месяцев.

  10. Убедитесь, что отладка веб-перехватчика выполняется так же, как на шаге 4.

  11. Нажмите кнопку Send (Отправить), чтобы выполнить запрос.

    Если запрос будет выполнен, появится ответ от SharePoint со сведениями о подписке. В следующем примере показан ответ для новой подписки:

    {
  "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449",
  "expirationDateTime": "2016-10-27T16:17:57Z",
  "id": "32b95d9-4d20-4a17-bfa3-2957cb38ead8",
  "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest",
  "resource": "c34420f9-2ad7-4e54-94c9-b67798d2299b"
}

  12. Скопируйте значение id подписки. Оно потребуется для следующего набора запросов.

  13. Перейдите к проекту приемника веб-перехватчиков в Visual Studio и просмотрите окно Выходные данные. В нем (наряду с другими сообщениями) должны отображаться журналы трассировки, подобные следующему:

    iisexpress.exe Information: 0 : Message='Received client state: A0A354EC-97D4-4D83-9DDB-144077ADB449'
iisexpress.exe Information: 0 : Message='Received validation token: daf2803c-43cf-44c7-8dff-7066eaa40f13'

    Трассировка указывает, что веб-перехватчик получил запрос на проверку. Изучив этот код, вы заметите, что он сразу возвращает маркер проверки, чтобы SharePoint мог проверить запрос:

    if (queryStringParams.AllKeys.Contains("validationtoken"))
{
  httpResponse = new HttpResponseMessage(HttpStatusCode.OK);
  validationToken = queryStringParams.GetValues("validationtoken")[0].ToString();
  httpResponse.Content = new StringContent(validationToken);

  traceWriter.Trace(Request, "SPWebhooks",
    TraceLevel.Info,
    string.Format("Received validation token: {0}", validationToken));
  return httpResponse;
}

Шаг 6. Получение сведений о подписке

Теперь мы выполним запросы на получение сведений о подписке в Postman.

  1. Откройте клиент Postman.

  2. Замените запрос POST на запрос GET.

  3. Введите следующий запрос:

    https://site-collection/_api/web/lists('list-id')/subscriptions

  4. Замените site-collection именем своего семейства веб-сайтов.

  5. Нажмите кнопку Send (Отправить), чтобы выполнить запрос.

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

    {
  "value": [
    {
      "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449",
      "expirationDateTime": "2016-10-27T16:17:57Z",
      "id": "32b95add-4d20-4a17-bfa3-2957cb38ead8",
      "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest",
      "resource": "c34420f9-2a67-4e54-94c9-b67798229f9b"
    }
  ]
}

  6. Выполните следующий запрос, чтобы получить сведения о подписке:

    https://site-collection/_api/web/lists('list-id')/subscriptions('subscription-id')

  7. Замените subscription-id идентификатором подписки.

Шаг 7. Тестирование уведомления веб-перехватчика

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

  1. Откройте Visual Studio.

  2. В элементе SPWebhookController добавьте точку останова на следующей строке кода:

    var requestContent = Request.Content.ReadAsStringAsync().Result;

  3. Перейдите к библиотеке Документы. В семействе веб-сайтов по умолчанию она называется Общие документы.

  4. Добавьте новый файл.

  5. Откройте Visual Studio и подождите, пока не будет достигнута точка останова.

    Это может занять от нескольких секунд до пяти минут. Когда будет достигнута точка останова, это означает, что приемник веб-перехватчиков только что получил уведомление от SharePoint.

  6. Нажмите клавишу F5, чтобы продолжить.

  7. Чтобы увидеть данные уведомления, найдите следующие записи в окне Выходные данные, так как вы добавили данные уведомления в журнал трассировки:

    iisexpress.exe Information: 0 : Message='Resource: c34420f9-2a67-4e54-94c9-b6770892299b'
iisexpress.exe Information: 0 : Message='SubscriptionId: 32b95ad9-4d20-4a17-bfa3-2957cb38ead8'
iisexpress.exe Information: 0 : Message='TenantId: 7a17cb7d-6898-423f-8839-45f363076f06'
iisexpress.exe Information: 0 : Message='SiteUrl: /'
iisexpress.exe Information: 0 : Message='WebId: 62b80e0b-f889-4974-a519-cc138413be40'
iisexpress.exe Information: 0 : Message='ExpirationDateTime: 2016-10-27T16:17:57.0000000Z'

Этот проект просто записывает сведения в журнал трассировки. Однако в нашем приемнике эти сведения отправляются в таблицу или очередь, которая может обрабатывать полученные данные для получения сведений из SharePoint.

С помощью этих данных вы можете составить URL-адрес и использовать API GetChanges для просмотра последних изменений.

Дальнейшие действия

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

Теперь ознакомьтесь с базовой реализацией веб-перехватчиков SharePoint, в которой для обработки сведений, получения изменений из SharePoint и их обратной передачи в список SharePoint используются Очереди хранилища Azure.