Эта страница переведена с помощью Cloud Translation API.

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

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

Обзор

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

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

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

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

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

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

Сделать запрос на просмотр

С каждым наблюдаемым ресурсом Admin SDK API связан метод watch по URI следующей формы:

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

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

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

Примеры

Все запросы на просмотр ресурса Activity имеют общий вид:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

Вы можете использовать параметры 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 символа.
Установленное вами значение идентификатора отображается в 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 (в удобочитаемом формате) в каждое сообщение уведомления, которое ваше приложение получает для этого канала.

Примечание. Для Admin SDK API максимальный срок действия составляет 21 600 секунд. Если вы не установили свойство expiration в своем запросе, время истечения срока действия по умолчанию будет равно 21600 секундам после текущего времени.

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

Посмотреть ответ

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

Примечание. Свойство resourceId — это стабильный, независимый от версии идентификатор ресурса. Свойство resourceUri — это канонический URI отслеживаемого ресурса в контексте текущей версии API, поэтому оно зависит от версии.

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

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

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

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

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

Примечание. В HTTPS-запросах доставки уведомлений указывается пользовательский агент APIs-Google и учитываются директивы robots.txt, как описано в разделе Пользовательский агент API Google .

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

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

Заголовки

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

Заголовок	Описание
Всегда присутствует
`X-Goog-Channel-ID`	UUID или другая уникальная строка, которую вы предоставили для идентификации этого канала уведомлений.
`X-Goog-Message-Number`	Целое число, идентифицирующее это сообщение для этого канала уведомлений. Значение всегда равно `1` для сообщений `sync` . Номера сообщений увеличиваются с каждым последующим сообщением в канале, но они не являются последовательными.
`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 . Время представляет собой полную дату плюс часы, минуты и секунды в формате ГГГГ-ММ-ДДТчч:мм:ссTZD. Например, 2010-04-05T17:30:04+01:00.
`id. uniqueQualifier`	Уникальный квалификатор, если несколько событий происходят в одно и то же время.
`id. applicationName`	Имя приложения, которому принадлежит событие. Возможные значения включают в себя: администратор календарь водить машину группы groups_enterprise авторизоваться мобильный Сэмл жетон учетные записи пользователей
`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`	Тип мероприятия. Служба или функция Google Workspace, которую изменяет администратор, определяется в свойстве `type` , которое идентифицирует событие с помощью свойства `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 // Your receiving URL.
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 // Your receiving URL.
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 , Admin SDK API повторяет попытку с экспоненциальной задержкой . Любой другой код статуса возврата считается ошибкой сообщения.

Понимание событий уведомлений 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"
}