Push-уведомления

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

Обзор

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

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

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

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

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

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

В настоящее время API каталога поддерживает уведомления об изменениях в ресурсе «Пользователи» .

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

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

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

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

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

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

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

Примеры

Все запросы на отслеживание ресурса User для одного домена имеют общий вид:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

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

  • token , который можно использовать в качестве токена вашего канала.
  • params ttl указывает время жизни (в секундах) для этого канала.

Используйте параметры domain и event , чтобы указать домен и тип события, для которого вы хотите получать уведомления.

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

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

Используйте параметры customer и event , чтобы указать уникальный идентификатор учетной записи Google клиента и тип события, о котором вы хотите получать уведомления.

Возможные значения для event :

  • add : событие, созданное пользователем
  • delete : событие удаления пользователем
  • makeAdmin : событие изменения статуса администратора пользователя
  • undelete : событие восстановления удаленных данных пользователем
  • update : пользователь обновил событие

Примечание: В приведенных ниже примерах для большей ясности текст запроса опущен.

Отслеживайте события, созданные пользователями для домена mydomain.com :

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Отслеживайте события, созданные пользователем для клиента my_customer :

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

Необходимые свойства

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

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

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

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

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

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

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

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

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

Ниже показан формат sync сообщений, которые 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 каталога (используется более строгое значение). Время истечения срока действия канала, если оно есть, включается в качестве метки времени Unix (в миллисекундах) в информацию, возвращаемую методом watch . Кроме того, дата и время истечения срока действия включаются (в удобочитаемом формате) в каждое сообщение уведомления, которое ваше приложение получает для этого канала, в HTTP-заголовке X-Goog-Channel-Expiration .

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

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

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

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

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

Заголовки

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

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

В теле запроса для пользователей содержатся следующие уведомления:

Свойство Описание
kind Идентифицирует это как ресурс пользователя. Значение: фиксированная строка " admin#directory#user ".
id Уникальный идентификатор ресурса пользователя.
etag ETag уведомления. Отличается от ETag ресурса пользователя.
primaryEmail Основной адрес электронной почты пользователя.

Примеры

Уведомления о событиях, связанных User ресурсами, имеют общий вид:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Пример события удаления пользователя:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

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

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

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

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

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

https://www.googleapis.com/admin/directory_v1/channels/stop

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

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

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

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

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

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