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

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

Обзор

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

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

  • Настройте принимающий URL или приемник обратного вызова «webhook».

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

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

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

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

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

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

Оформить запрос на просмотр

Каждый доступный для просмотра ресурс 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", // 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 , которые 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 Диска отправляет эти сообщения в виде HTTPS-запросов POST на URL-адрес, указанный вами в качестве свойства address для этого канала уведомлений.

Интерпретировать формат сообщения уведомления

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

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

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

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

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"
}
,

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

Обзор

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

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

  • Настройте принимающий URL или приемник обратного вызова «webhook».

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

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

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

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

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

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

Оформить запрос на просмотр

Каждый доступный для просмотра ресурс 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", // 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 , которые 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 Диска отправляет эти сообщения в виде HTTPS-запросов POST на URL-адрес, указанный вами в качестве свойства address для этого канала уведомлений.

Интерпретировать формат сообщения уведомления

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

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

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

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

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"
}