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

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

Обзор

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

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

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

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

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

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

В настоящее время API Admin SDK поддерживает уведомления об изменениях в ресурсе Activities .

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

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

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

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

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

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

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

Примеры

Все запросы на добавление в избранное раздела «Мероприятия» имеют общий вид:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/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-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

Тело запроса обладает следующими свойствами:

  • id : UUID или аналогичная уникальная строка, идентифицирующая этот канал.
  • type : Тип механизма доставки. Значение этого поля должно быть web_hook .
  • address : URL-адрес, куда отправляются уведомления.
  • token : Произвольная строка, отправляемая на целевой адрес с каждым уведомлением с целью проверки того, что уведомление поступает из надежного источника.
  • payload : Логический флаг, указывающий, следует ли включать полезную нагрузку в уведомление.
  • expiration : Время жизни канала уведомлений в секундах.

Вы можете использовать параметры userKey , applicationName , eventName и filters , чтобы получать уведомления только о конкретных событиях, пользователях или приложениях.

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

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

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Следите за всеми действиями, связанными с документами:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Отслеживайте активность администратора конкретного пользователя:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

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

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Следите за изменениями в конкретном документе:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

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

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

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

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

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

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

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

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

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

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

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

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

Заголовки

Уведомления, отправляемые API Admin SDK на ваш 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#reports#activity ".
id Уникальный идентификатор записи о деятельности.
id. time Время выполнения действия. Значение представлено в формате даты и времени ISO 8601. Время представляет собой полную дату плюс часы, минуты и секунды в формате ГГГГ-ММ-ДДТЧ:мм:ссТЗД. Например, 2010-04-05T17:30:04+01:00.
id. uniqueQualifier Уникальный квалификационный критерий, если несколько событий имеют одинаковое время.
id. applicationName Название приложения, к которому относится событие. Возможные значения:
id. customerId Уникальный идентификатор учетной записи Google Workspace.
actor Пользователь выполняет действие.
actor. callerType Тип автора, выполнившего действия, указанные в отчете. В этой версии API callerType — это USER или объект запроса OAuth 2LO, выполнивший действие, указанное в отчете.
actor. email Основной адрес электронной почты пользователя, о действиях которого ведется отчетность.
actor. profileId Уникальный идентификатор профиля пользователя в Google Workspace.
ownerDomain Домен административной консоли или владельца документа в приложении «Документы». Это домен, на который влияет событие отчета.
ipAddress IP-адрес пользователя, выполняющего действие. Это IP-адрес пользователя при входе в Google Workspace, который может отражать или не отражать его физическое местоположение. Например, IP-адрес может совпадать с адресом прокси-сервера пользователя или адресом виртуальной частной сети (VPN). API поддерживает IPv4 и IPv6 .
events[] События, описанные в отчете.
events[]. type Тип события. В свойстве type указывается служба или функция Google Workspace, которую изменяет администратор, а свойство eventName определяет событие.
events[]. name Название события. Это конкретное название действия, о котором сообщает API. Каждое eventName связано с определенной службой или функцией Google Workspace, которую API организует по типам событий.
Что касается параметров запроса eventName в целом:
  • Если eventName не указан, отчет возвращает все возможные экземпляры eventName .
  • При запросе eventName API возвращает все действия, содержащие это eventName . Возможно, что возвращенные действия будут иметь и другие свойства eventName помимо запрошенного.
events[]. parameters[] Пары «параметр-значение» для различных приложений.
events[].parameters[]. name Название параметра.
events[].parameters[]. value Строковое значение параметра.
events[].parameters[]. intValue Целочисленное значение параметра.
events[].parameters[]. boolValue Логическое значение параметра.

Примеры

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

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
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/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

Пример события, связанного с административной деятельностью: 

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

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

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

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

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

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

Push-уведомления API отчетов содержат два типа сообщений: сообщения синхронизации и уведомления о событиях. Тип сообщения указывается в HTTP-заголовке X-Goog-Resource-State . Возможные значения для уведомлений о событиях совпадают с значениями для метода activities.list . Каждое приложение имеет уникальные события:

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

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

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

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

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

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

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

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

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