Всплывающее уведомление

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

Обзор

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

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

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

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

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

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

В настоящее время API Google Календаря поддерживает уведомления об изменениях в ресурсах Acl , CalendarList , Events и Settings .

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

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

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

Каждый ресурс Google Calendar API, доступный для просмотра, имеет связанный с ним метод watch по URI следующего вида:

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

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

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

Пример

Начните отслеживать изменения в наборе событий в заданном календаре:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "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 Календаря может отправлять уведомления на этот 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 для ресурсов Acl , CalendarList , Events и Settings в справочнике API.

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

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

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

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

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

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

Для получения более подробной информации об ответе обратитесь к методу watch для ресурсов Acl , CalendarList , Events и Settings в справочнике 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 Календаря отправляет на ваш 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-заголовки:

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

Уведомления, отправляемые API Google Календаря на ваш URL-адрес получателя, не содержат текста сообщения. Эти сообщения не содержат конкретной информации об обновленных ресурсах; для просмотра полной информации об изменениях вам потребуется выполнить еще один вызов API.

Примеры

Сообщение уведомления об изменении набора событий:

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/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

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

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

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

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

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

X-Goog-Resource-State Применяется к Доставка осуществляется в установленное время.
sync Списки контроля доступа (ACL), списки календаря, события, настройки. Новый канал успешно создан. Вы начнете получать уведомления о его работе.
exists Списки контроля доступа (ACL), списки календаря, события, настройки. Произошли изменения в ресурсе. Возможные изменения включают создание нового ресурса, а также изменение или удаление существующего ресурса.

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

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

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

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

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

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

Следующий пример кода показывает, как отключить получение уведомлений:

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

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