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

Получение уведомлений между службами с помощью веб-перехватчиков

  • Статья

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

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

Распространенные задачи

Задача Метод HTTP
Создание подписки POST /subscriptions
Удаление подписки DELETE /subscriptions/{id}
Обновление подписки PATCH /subscriptions/{id}

Регистрация

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

Сведения о том, как зарегистрировать URL-адрес для уведомлений, см. в статье Добавление новой подписки.

Область уведомлений

Уведомления веб-перехватчиков будут отправляться приложению только для изменений, соответствующих следующим условиям:

  • Пользователь разрешил приложению доступ к содержимому OneDrive.
  • У приложения есть доступ к элементу, который создает уведомление.
  • Срок действия подписки не истек.

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

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

После создания подписки OneDrive отправляет запросы POST на зарегистрированный URL-адрес при изменении элементов в области уведомлений. Несколько уведомлений для службы могут быть объединены в один запрос, если за один период времени произошли изменения у нескольких пользователей.

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

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

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

Обратите внимание, что уведомление не включает сведения о вызвавших его изменениях. Предполагается, что приложение будет использовать команду delta, чтобы определить изменения в состоянии элементов в OneDrive и сохранить значение syncToken для следующего уведомления.

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

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

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

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

Для новых подписок автоматически задается дата окончания срока действия, если она не была указана при создании подписки. По умолчанию срок действия подписки завершается спустя 6 месяцев после ее создания.

Рекомендации

При использовании веб-перехватчиков следует учитывать некоторые важные аспекты:

Работа между службами

Не следует пытаться использовать веб-перехватчики для непосредственного уведомления клиентских устройств. У каждого приложения есть один URL-адрес веб-перехватчика, который вызывается для всех пользователей. Этот URL-адрес должен указывать на контролируемую вами службу. Вы можете сделать так, чтобы служба анализировала сообщения и пересылала соответствующие push-уведомления клиентским приложениям по вашему усмотрению.

Быстрый ответ

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

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

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