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

Обязательные свойства

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

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

Если запрос 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 для идентификации ресурса, отслеживаемого в этом канале уведомлений.

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

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

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

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

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

Сообщения уведомлений для действий содержат в теле запроса следующую информацию:

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 . Каждое приложение имеет уникальные события:

• администратор
• календарь
• водить машину
• группы
• авторизоваться
• мобильный
• Сэмл
• жетон
• user_accounts