Уведомления об изменениях ресурсов

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

Обзор

Google Drive API поддерживает push-уведомления, которые позволяют отслеживать изменения в ресурсах. Эта функция позволяет повысить эффективность приложения. Это позволяет избежать дополнительных сетевых и вычислительных затрат, связанных с опросом ресурсов для определения того, изменились ли они. При изменении отслеживаемого ресурса Google Drive API отправляет уведомление в ваше приложение.

Чтобы использовать push-уведомления, необходимо выполнить два действия:

  • Настройте URL получателя или получатель обратного вызова вебхука.

    Это HTTPS-сервер, который обрабатывает уведомления API, активируемые при изменении ресурса.

  • Настройте канал уведомлений для каждой конечной точки ресурса, которую вы хотите отслеживать.

    Канал содержит информацию о маршрутизации для сообщений с уведомлениями. При настройке канала необходимо указать URL, по которому вы хотите получать уведомления. При изменении ресурса канала Google Drive API отправляет уведомление в виде запроса POST на этот URL.

В настоящее время Google Drive API поддерживает уведомления об изменениях для методов files и changes.

Создание каналов уведомлений

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

Как отправлять запросы на просмотр

У каждого отслеживаемого ресурса Google Drive API есть связанный метод watch с URI следующего вида:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

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

Каждый канал уведомлений связан с определенным пользователем и определенным ресурсом (или набором ресурсов). Запрос watch будет выполнен успешно, только если текущий пользователь или сервисный аккаунт является владельцем этого ресурса или имеет разрешение на доступ к нему.

Примеры

В примере кода ниже показано, как использовать ресурс channels, чтобы начать отслеживать изменения в одном ресурсе files с помощью метода files.watch.

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

В теле запроса укажите канал id, type как web_hook и URL получателя в address. Вы также можете указать:

  • token, который будет использоваться в качестве токена канала.
  • expiration время в миллисекундах, когда истекает срок действия запрошенного канала.

В примере кода ниже показано, как использовать ресурс channels, чтобы начать отслеживать все changes с помощью метода changes.watch.

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

В теле запроса укажите канал id, type как web_hook и URL получателя в address. Вы также можете указать:

  • token, который будет использоваться в качестве токена канала.
  • expiration время в миллисекундах, когда истекает срок действия запрошенного канала.

Обязательные свойства

В каждом запросе watch необходимо указать следующие поля:

  • Строка свойства id, которая уникальным образом идентифицирует этот новый канал уведомлений в вашем проекте. Рекомендуем использовать универсальный уникальный идентификатор (UUID) или любую другую уникальную строку. Максимальная длина – 64 символа.

    Заданное значение идентификатора будет возвращаться в HTTP-заголовке X-Goog-Channel-Id каждого уведомления, полученного для этого канала.

  • Строка свойства type со значением web_hook.

  • Строка свойства address, в которой указан URL, принимающий уведомления для этого канала и отвечающий на них. Это URL обратного вызова вебхука, и он должен использовать HTTPS.

    Обратите внимание, что Google Drive API может отправлять уведомления на этот адрес HTTPS, только если на вашем веб-сервере установлен действительный SSL-сертификат. Недействительными считаются следующие варианты:

    • Сертификаты с собственной подписью.
    • Сертификаты с подписью из ненадежного источника.
    • Отозванные сертификаты.
    • Сертификаты, объект которых не соответствует целевому имени хоста.

Необязательные свойства

В запросе watch можно также указать следующие необязательные поля:

  • Свойство token, которое задает произвольное строковое значение, используемое в качестве токена канала. Токены каналов уведомлений можно использовать для разных целей. Например, с помощью токена можно проверить, что входящее сообщение предназначено для канала, созданного вашим приложением (чтобы убедиться, что уведомление не поддельное), или направить сообщение в нужное место в приложении в зависимости от назначения этого канала. Максимальная длина – 256 символов.

    Токен включается в HTTP-заголовок X-Goog-Channel-Token каждого уведомления, которое ваше приложение получает по этому каналу.

    Если вы используете токены каналов уведомлений, рекомендуем:

    • Используйте расширяемый формат кодирования, например параметры запроса URL. Пример: forwardTo=hr&createdBy=mobile

    • Не указывайте конфиденциальные данные, например токены OAuth.

  • Строка свойства expiration, в которой указана временная метка Unix (в миллисекундах) для даты и времени, когда Google Drive API должен прекратить отправку сообщений для этого канала уведомлений.

    Если у канала есть срок действия, он указывается в качестве значения HTTP-заголовка X-Goog-Channel-Expiration (в человекочитаемом формате) в каждом уведомлении, которое ваше приложение получает для этого канала.

Подробную информацию о запросе можно найти в описании метода watch для методов files и changes в документации по API.

Посмотреть ответ

Если запрос watch успешно создает канал уведомлений, он возвращает код статуса HTTP 200 OK.

В теле ответа на запрос watch содержится информация о созданном канале уведомлений, как показано в примере ниже.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

В теле ответа содержатся сведения о канале, например:

  • kind – указывает, что это ресурс канала API.
  • id – идентификатор, который вы указали для этого канала.
  • resourceId – идентификатор отслеживаемого ресурса.
  • resourceUri – идентификатор отслеживаемого ресурса, относящийся к определенной версии.
  • token: токен, указанный в теле запроса.
  • expiration – время окончания действия канала в формате временной метки Unix в миллисекундах.

Помимо свойств, отправленных в запросе, возвращаемая информация также включает resourceId и resourceUri для идентификации ресурса, отслеживаемого в этом канале уведомлений.

Возвращенную информацию можно передавать другим операциям канала уведомлений, например когда вы хотите прекратить получать уведомления.

Подробную информацию об ответе можно найти в описании метода watch для методов files и changes в документации по API.

Сообщение о синхронизации

После создания канала уведомлений для отслеживания ресурса Google Drive API отправляет сообщение sync, чтобы указать, что уведомления начинают поступать. Значение HTTP-заголовка X-Goog-Resource-State для таких сообщений – sync. Из-за задержек в сети сообщение sync может прийти даже раньше, чем ответ метода watch.

Уведомление sync можно проигнорировать, но вы также можете им воспользоваться. Например, если вы решите, что канал вам больше не нужен, вы можете использовать значения X-Goog-Channel-ID и X-Goog-Resource-ID в вызове, чтобы прекратить получать уведомления. Уведомление sync также можно использовать для инициализации, чтобы подготовиться к последующим событиям.

Ниже показан формат сообщений sync, которые Google Drive API отправляет на ваш URL получения.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Синхронизирующие сообщения всегда имеют значение заголовка HTTP X-Goog-Message-Number, равное 1. Каждое последующее уведомление для этого канала имеет номер сообщения, который больше предыдущего, хотя номера сообщений не будут последовательными.

Обновление каналов уведомлений

Канал уведомлений может иметь срок действия, значение которого определяется либо вашим запросом, либо внутренними ограничениями или значениями по умолчанию Google Drive API (используется более строгое значение). Если у канала есть срок действия, он указывается в виде временной метки Unix (в миллисекундах) в информации, возвращаемой методом watch. Кроме того, дата и время окончания срока действия указываются в человекочитаемом формате в HTTP-заголовке X-Goog-Channel-Expiration каждого уведомления, которое ваше приложение получает для этого канала.

В настоящее время автоматическое продление канала уведомлений не поддерживается. Когда срок действия канала подходит к концу, его необходимо заменить новым, вызвав метод watch. Как и всегда, для свойства id нового канала необходимо использовать уникальное значение. Обратите внимание, что в течение некоторого времени могут быть активны оба канала уведомлений для одного ресурса.

Получайте оповещения.

При изменении отслеживаемого ресурса приложение получает уведомление с описанием изменения. Google Drive API отправляет эти сообщения в виде HTTPS-запросов POST на URL, указанный вами в качестве свойства address для этого канала уведомлений.

Как интерпретировать формат уведомления

Все уведомления содержат набор HTTP-заголовков с префиксами X-Goog-. Некоторые типы уведомлений могут также содержать текст сообщения.

заголовки;

Уведомления, отправляемые Google Drive API на ваш URL, содержат следующие HTTP-заголовки:

Заголовок Описание
Всегда показывать
X-Goog-Channel-ID UUID или другая уникальная строка, которую вы указали для идентификации этого канала уведомлений.
X-Goog-Message-Number Целое число, которое идентифицирует это сообщение для этого канала уведомлений. Для сообщений sync значение всегда равно 1. Номера сообщений увеличиваются для каждого последующего сообщения на канале, но они не являются последовательными.
X-Goog-Resource-ID Непрозрачное значение, идентифицирующее отслеживаемый ресурс. Этот идентификатор не меняется в разных версиях API.
X-Goog-Resource-State Новое состояние ресурса, которое активировало уведомление. Возможные значения: sync, add, remove, update, trash, untrash или change .
X-Goog-Resource-URI Идентификатор отслеживаемого ресурса, зависящий от версии API.
Иногда присутствует
X-Goog-Changed Дополнительные сведения об изменениях. Возможные значения: content, parents, children или permissions. Не предоставляется с сообщениями sync.
X-Goog-Channel-Expiration Дата и время окончания срока действия канала уведомлений в человекочитаемом формате. Присутствует, только если определено.
X-Goog-Channel-Token Токен канала уведомлений, заданный вашим приложением. С его помощью можно проверить источник уведомления. Присутствует, только если определено.

Уведомления для ресурсов files (включая события add, remove, update, trash и untrash) и ресурсов changes всегда пустые (тело HTTP-запроса пустое, т.е. Content-Length: 0).

Примеры

Уведомление для ресурсов files при добавлении ресурса (тело запроса пустое):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID: ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State: add
X-Goog-Message-Number: 10

Изменить сообщение уведомления для ресурсов files при обновлении ресурса (тело запроса пустое):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID: ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State: update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 11

Сообщение об изменении для ресурсов changes (тело запроса пустое):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID: ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State: changed
X-Goog-Message-Number: 23

Работа с оповещениями

Чтобы указать на успешное выполнение, можно вернуть любой из следующих кодов статуса: 200, 201, 202, 204 или 102.

Если ваш сервис использует клиентскую библиотеку Google API и возвращает 500, 502, 503 или 504, Google Drive API повторит попытку с экспоненциальной выдержкой. Любой другой код статуса возврата считается ошибкой сообщения.

События уведомлений Google Drive API

В этом разделе подробно описаны уведомления, которые вы можете получать при использовании push-уведомлений с Google Drive API.

X-Goog-Resource-State Область применения Когда доставляется
sync files, changes Канал создан. Вы начнете получать уведомления о нем.
add files Ресурс был создан или им поделились.
remove files Существующий ресурс был удален или доступ к нему был закрыт.
update files Обновлено одно или несколько свойств (метаданных) ресурса.
trash files Ресурс перемещен в корзину.
untrash files Ресурс удален из корзины.
change changes Добавлен один или несколько пунктов в журнал изменений.

Для событий update может быть предоставлен HTTP-заголовок X-Goog-Changed. Этот заголовок содержит список, разделенный запятыми, в котором описываются типы произошедших изменений.

Тип изменения Обозначает
content Контент ресурса обновлен.
properties Одно или несколько свойств ресурса были обновлены.
parents Добавлен или удален один или несколько родительских ресурсов.
children Добавлен или удален один или несколько дочерних ресурсов.
permissions Разрешения для ресурса обновлены.

Пример с заголовком X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

Уведомления об остановке

Свойство expiration определяет, когда уведомления автоматически прекращаются. Вы можете отказаться от получения уведомлений для определенного канала до истечения срока его действия, вызвав метод stop по следующему URI:

https://www.googleapis.com/drive/v3/channels/stop

При вызове этого метода необходимо указать как минимум свойства id и resourceId канала, как показано в примере ниже. Обратите внимание, что если в Google Drive API есть несколько типов ресурсов с методами watch, то метод stop только один.

Остановить канал могут только пользователи с соответствующим разрешением. В их числе:

  • Если канал был создан обычным аккаунтом пользователя, то остановить его может только тот же пользователь из того же клиента (определяется по идентификаторам клиентов OAuth 2.0 из токенов аутентификации), который создал канал.
  • Если канал был создан сервисным аккаунтом, то остановить его может любой пользователь того же клиента.

В приведенном ниже фрагменте кода показано, как отключить получение уведомлений.

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}