В этом документе описывается, как использовать push-уведомления, которые информируют ваше приложение об изменении ресурса.
Обзор
API Google Диска предоставляет push-уведомления, которые позволяют отслеживать изменения в ресурсах. Вы можете использовать эту функцию для повышения производительности вашего приложения. Это позволяет исключить дополнительные сетевые и вычислительные затраты, связанные с опросом ресурсов, чтобы определить, изменились ли они. При каждом изменении отслеживаемого ресурса API Google Диска уведомляет ваше приложение.
Чтобы использовать push-уведомления, вам необходимо сделать две вещи:
Настройте URL-адрес получения или приемник обратного вызова «вебхук».
Это HTTPS-сервер, который обрабатывает сообщения уведомлений API, которые запускаются при изменении ресурса.
Настройте ( канал уведомлений ) для каждой конечной точки ресурса, которую вы хотите отслеживать.
Канал определяет информацию о маршрутизации для сообщений уведомлений. В рамках настройки канала вы должны указать конкретный URL-адрес, по которому вы хотите получать уведомления. Всякий раз, когда ресурс канала изменяется, API Google Диска отправляет уведомление в виде запроса
POST
на этот URL-адрес.
В настоящее время API Google Диска поддерживает уведомления об изменениях files
и методов changes
.
Создание каналов уведомлений
Чтобы запросить push-уведомления, вам необходимо настроить канал уведомлений для каждого ресурса, который вы хотите отслеживать. После настройки каналов уведомлений API Google Диска информирует ваше приложение об изменении любого просматриваемого ресурса.
Сделать запрос на просмотр
Каждый доступный для просмотра ресурс API Google Диска имеет связанный метод 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", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
В следующем примере кода показано, как использовать ресурс 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", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token. "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time. }
Обязательные свойства
При каждом запросе watch
необходимо указать следующие поля:
Строка свойства
id
, которая уникально идентифицирует этот новый канал уведомлений в вашем проекте. Мы рекомендуем использовать универсальный уникальный идентификатор ( UUID ) или любую подобную уникальную строку. Максимальная длина: 64 символа.Установленное вами значение идентификатора отображается в HTTP-заголовке
X-Goog-Channel-Id
каждого уведомления, которое вы получаете для этого канала.Строка свойства
type
, для которой установлено значениеweb_hook
.Строка свойства
address
, равная URL-адресу, который прослушивает уведомления для этого канала уведомлений и отвечает на них. Это URL-адрес обратного вызова вашего веб-перехватчика, и он должен использовать HTTPS.Обратите внимание, что API Google Диска может отправлять уведомления на этот адрес HTTPS только в том случае, если на вашем веб-сервере установлен действительный сертификат SSL. К недействительным сертификатам относятся:
- Самоподписанные сертификаты.
- Сертификаты, подписанные ненадежным источником.
- Сертификаты, которые были отозваны.
- Сертификаты, тема которых не соответствует целевому имени хоста.
Дополнительные свойства
Вы также можете указать эти необязательные поля в запросе watch
:
Свойство
token
, указывающее произвольное строковое значение, которое будет использоваться в качестве токена канала. Вы можете использовать токены канала уведомлений для различных целей. Например, вы можете использовать токен, чтобы убедиться, что каждое входящее сообщение предназначено для канала, созданного вашим приложением, — чтобы гарантировать, что уведомление не является поддельным, — или для маршрутизации сообщения в правильный пункт назначения в вашем приложении в зависимости от цели этот канал. Максимальная длина: 256 символов.Токен включается в HTTP-заголовок
X-Goog-Channel-Token
в каждом сообщении уведомления, которое ваше приложение получает для этого канала.Если вы используете токены канала уведомлений, мы рекомендуем вам:
Используйте расширяемый формат кодирования, например параметры URL-запроса. Пример:
forwardTo=hr&createdBy=mobile
Не включайте конфиденциальные данные, такие как токены OAuth.
Строка свойства
expiration
, равная временной метке Unix (в миллисекундах) даты и времени, когда вы хотите, чтобы API Google Диска прекратил отправку сообщений для этого канала уведомлений.Если у канала есть срок действия, он включается в качестве значения HTTP-заголовка
X-Goog-Channel-Expiration
(в удобочитаемом формате) в каждое сообщение уведомления, которое ваше приложение получает для этого канала.
Для получения более подробной информации о запросе обратитесь к методу watch
за files
и методам changes
в справочнике по API.
Посмотреть ответ
Если запрос watch
успешно создает канал уведомлений, он возвращает код состояния HTTP 200 OK
.
Тело сообщения ответа на просмотр предоставляет информацию о только что созданном канале уведомлений, как показано в примере ниже.
{ "kind": "api#channel", "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable. }
В дополнение к свойствам, которые вы отправили в рамках вашего запроса, возвращаемая информация также включает в себя resourceId
и resourceUri
для идентификации ресурса, отслеживаемого в этом канале уведомлений.
Вы можете передать возвращенную информацию другим операциям канала уведомлений, например, когда вы хотите прекратить получение уведомлений .
Дополнительные сведения об ответе см. в разделе «метод watch
за files
и методы changes
в справочнике по API.
Синхронизировать сообщение
После создания канала уведомлений для просмотра ресурса API Google Диска отправляет сообщение 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
. Каждое последующее уведомление для этого канала имеет номер сообщения, больший, чем предыдущее, однако номера сообщений не будут последовательными.
Обновить каналы уведомлений
Канал уведомлений может иметь срок действия, значение которого определяется либо вашим запросом, либо любыми внутренними ограничениями или значениями по умолчанию API Google Диска (используется более ограничительное значение). Время истечения срока действия канала, если оно есть, включается в качестве временной метки Unix (в миллисекундах) в информацию, возвращаемую методом watch
. Кроме того, дата и время истечения срока действия включаются (в удобочитаемом формате) в каждое уведомление, которое ваше приложение получает для этого канала, в HTTP-заголовке X-Goog-Channel-Expiration
.
В настоящее время не существует автоматического способа продления канала уведомлений. Когда срок действия канала близок к истечению, вы должны заменить его новым, вызвав метод watch
. Как всегда, вы должны использовать уникальное значение для свойства id
нового канала. Обратите внимание, что, скорее всего, будет период «перекрытия», когда два канала уведомлений для одного и того же ресурса будут активны.
Получать уведомления
При каждом изменении отслеживаемого ресурса ваше приложение получает уведомление с описанием изменения. API Google Диска отправляет эти сообщения в виде запросов HTTPS POST
на URL-адрес, указанный вами в качестве свойства address
для этого канала уведомлений.
Интерпретация формата уведомления
Все сообщения уведомлений включают набор заголовков HTTP с префиксами X-Goog-
. Некоторые типы уведомлений также могут включать тело сообщения.
Заголовки
Уведомления, отправляемые API Google Диска на ваш URL-адрес получения, включают следующие заголовки HTTP:
Заголовок | Описание |
---|---|
Всегда присутствует | |
| UUID или другая уникальная строка, которую вы предоставили для идентификации этого канала уведомлений. |
| Целое число, идентифицирующее это сообщение для этого канала уведомлений. Значение всегда равно 1 для сообщений sync . Номера сообщений увеличиваются с каждым последующим сообщением в канале, но они не являются последовательными. |
| Непрозрачное значение, идентифицирующее отслеживаемый ресурс. Этот идентификатор стабилен во всех версиях API. |
| Новое состояние ресурса, вызвавшее уведомление. Возможные значения: sync , add , remove , update , trash , untrash или change . |
| Идентификатор отслеживаемого ресурса, зависящий от версии API. |
Иногда присутствует | |
| Дополнительные подробности об изменениях. Возможные значения: content , parents , children или permissions . Не предусмотрены сообщения sync . |
| Дата и время истечения срока действия канала уведомления, выраженные в удобочитаемом формате. Присутствует, только если определено. |
| Токен канала уведомлений, установленный вашим приложением и который вы можете использовать для проверки источника уведомлений. Присутствует, только если определено. |
Уведомления о files
и changes
пусты.
Примеры
Измените сообщение уведомления для files
ресурсов, которое не содержит тела запроса:
POST https://mydomain.com/notifications // Your receiving URL. 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 // Your receiving URL. 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
, Google Drive API повторяет попытку с экспоненциальной задержкой . Любой другой код статуса возврата считается ошибкой сообщения.
Понимание событий уведомлений API Google Диска
В этом разделе представлена подробная информация об уведомлениях, которые вы можете получать при использовании push-уведомлений с API Google Диска.
| | Доставлено, когда |
---|---|---|
sync | files , changes | Канал успешно создан. Вы можете рассчитывать на то, что начнете получать уведомления об этом. |
add | files | Ресурс был создан или опубликован. |
| files | Существующий ресурс был удален или закрыт доступ к нему. |
| files | Обновлены одно или несколько свойств (метаданных) ресурса. |
| files | Ресурс перемещен в корзину. |
| files | Ресурс удален из корзины. |
| 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 Диска имеет несколько типов ресурсов с методами 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" }