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

  • Статья

Область применения: Пользовательские записные книжки в OneDrive****

Подпишитесь на услугу Webhooks и будьте в курсе изменений, которые ваши пользователи выполняют в OneNote.

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

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

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

Уведомления отправляются как запросы POST, содержащие объект JSON, как показано в следующем примере.

{
  "value":[
    {
      "subscriptionId":"client-id-of-your-registered-application",
      "userId":"id-of-the-user-who-owns-the-changed-resource" 
    }
  ]
}

Ваша служба должна незамедлительно ответить на уведомление одним из следующих кодов состояния HTTP:

  • 200 OK
  • 202 Принято
  • 204 Нет содержимого

Если мы не получим ответ, мы повторим отправку несколько раз с экспоненциальной отсрочкой, после чего отменим отправку сообщения.

Дополнительные сведения об уведомлениях

  • Уведомления охватывают содержимое, принадлежащее вашим пользователям, независимо от того, кто внес изменения. Уведомления не отправляются в отношении изменений, внесенных в контент, доступный для ваших пользователей. Поэтому, если Боб (не ваш пользователь) внесет изменения в записную книжку, принадлежащую Алисе (ваш пользователь), вы получите уведомление с идентификатором пользователя Алисы. Вы не получите уведомление, если Алиса внесет изменение в записную книжку Боба.

  • Идентификатор пользователя userId в уведомлении соответствует идентификатору, который возвращается в заголовке X-AuthenticatedUserId ответов OneNote API.

  • Изменения, сделанные в течение короткого промежутка времени, могут быть объединены в одно уведомление.

  • Уведомления обычно отправляются в течение нескольких минут после изменения. Такое время ожидания гарантирует, что изменения будут доступны для API, хотя изменение может быть доступно сразу же в клиенте.

Рабочий процесс уведомлений

Типичный рабочий процесс уведомлений высокого уровня выглядит примерно так:

  1. Изменения вносятся в записную книжку, принадлежащую одному из ваших пользователей.
  2. OneNote отправляет один или несколько запросов POST на ваш зарегистрированный URL обратного вызова. Каждый запрос POST представляет одно или несколько изменений.
  3. Ваша служба отвечает на каждый запрос POST с кодом состояния HTTP 200, 202 или 204.
  4. Уведомления активируют обработчик событий в вашем API обратного вызова.
  5. Вы запрашиваете службу OneNote на предмет подробных изменений.

Запрос, основанный на временной метке последнего изменения, является наилучшим способом обеспечить фиксацию всех изменений. Сохраните временную метку из последних lastModifiedTime из результатов, затем используйте её в следующем запросе на изменение.

Этот запрос использует свойство lastModifiedTime, чтобы вернуть все страницы, которые изменились с момента вашей сохраненной временной метки:

GET ../me/notes/pages?filter=lastModifiedTime%20ge%20{stored-iso-8601-timestamp}

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

Примечание

Служба Webhooks не предназначена для использования в качестве механизма синхронизации. В случае, если уведомление не может быть отправлено или получено, следует периодически запрашивать изменения.

Подписаться на услугу Webhooks

Чтобы подписаться на услугу Webhooks OneNote, вам необходимо:

  • Зарегистрировать URL-адрес обратного вызова, который является общедоступной конечной точкой (HTTP или HTTPS), где вы будете получать запросы HTTP POST от службы Webhooks OneNote. Услуга Webhooks не будет следовать переадресации HTTP.

  • Запросите следующие разрешения для своего приложения:

    • wl.offline_access (Разрешение учетной записи Microsoft)
    • office.onenote, office.onenote_create, office.onenote_update_by_app, или office.onenote_update для API OneNote, в зависимости от того, что делает ваше приложение

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

Когда ваши пользователи регистрируются в вашем приложении, вы должны осуществить вызов в API OneNote от их имени (например: GET../me/notes/notebooks). Этот вызов будет:

  • Убедитесь, что OneNote регистрирует пользователя для уведомлений обратного вызова.
  • Позволяет получать и сохранять идентификатор пользователя, который возвращается в заголовке ответа X-AuthenticatedUserId.

Модель истечения срока действия

Для уведомлений webhook мы регистрируем идентификаторы ваших пользователей. Каждое взаимодействие, осуществленное данным пользователем, возобновляет регистрацию пользователя на шесть месяцев.

Регистрация становится неактивной после шестимесячного периода, в течение которого вы не вызывали API OneNote от имени данного пользователя. Вы не будете получать уведомления для неактивных пользователей, включая пользователей, которые удаляют ваше приложение или отменяют его разрешения.

Поскольку уведомления об изменениях не содержат сведений о пользователе или изменении, уменьшается потенциальный риск для конфиденциальности пользователей. Неактивные пользователи перерегистрируются, когда вы вызываете OneNote API от их имени.

См. также