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

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

Обзор

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

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

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

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

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

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

Примечание: Слово «канал», используемое в этом документе, относится исключительно к каналу уведомлений, а не к каким-либо другим типам каналов, используемых в этом API или сервисе. Для одного и того же ресурса может быть одновременно активно несколько каналов уведомлений.

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

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

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

Отправляйте запросы на просмотр.

Каждый ресурс API Google Drive, доступный для отслеживания, имеет связанный с ним метод 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 символа.

  Указанное вами значение ID будет отражено в HTTP-заголовке X-Goog-Channel-Id каждого уведомления, которое вы получаете для этого канала.

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

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

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

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

Дополнительные свойства

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

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

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

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

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

  • Не включайте конфиденциальные данные, такие как токены OAuth.

  Примечание: Если вам необходимо отправить особо конфиденциальные данные, убедитесь, что они зашифрованы, прежде чем добавлять их в токен.

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

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

Примечание: для API Google Drive максимальное время истечения срока действия составляет 86400 секунд (1 день) после текущего времени для ресурса files и 604800 секунд (1 неделя) для changes . Если вы не укажете свойство expiration в своем запросе, время истечения срока действия по умолчанию составит 3600 секунд после текущего времени.

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

Ответ на просмотр

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

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

{
  "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 для идентификации ресурса, отслеживаемого в этом канале уведомлений.

Примечание: Свойство resourceId — это стабильный, независимый от версии идентификатор ресурса. Свойство resourceUri — это канонический URI отслеживаемого ресурса в контексте текущей версии API, поэтому оно зависит от версии.

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

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

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

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

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

Ниже показан формат сообщений sync , которые API Google Drive отправляет на ваш 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 Каждое последующее уведомление для этого канала имеет номер сообщения, больший, чем предыдущий, хотя номера сообщений не будут последовательными.

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

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

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

Получать уведомления

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

Примечание: HTTPS-запросы для доставки уведомлений указывают пользовательский агент APIs-Google и учитывают директивы robots.txt, как описано в разделе «Пользовательский агент API Google» .

Интерпретируйте формат уведомления.

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

Заголовки

Уведомления, отправляемые API Google Drive на ваш 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	Токен канала уведомлений, установленный вашим приложением, который вы можете использовать для проверки источника уведомлений. Присутствует только в том случае, если он определен.

Уведомления об changes и files отсутствуют.

Примеры

Измените сообщение уведомления для 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: 398348u3tu83ut8uu38
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: 10

Уведомление об changes ресурсов, содержащее текст запроса:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 118
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

{
  "kind": "drive#changes"
}

Отвечать на уведомления

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

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

Понимание событий уведомлений API Google Drive

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

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 , как показано в примере ниже. Обратите внимание, что если API Google Drive содержит несколько типов ресурсов с методами 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"
}