REST Resource: subscriptions

Ресурс: Подписка

Подписка на получение событий, связанных с ресурсом Google Workspace. Подробнее о подписках см. в обзоре API событий Google Workspace .

JSON-представление 
{
  "name": string,
  "uid": string,
  "targetResource": string,
  "eventTypes": [
    string
  ],
  "payloadOptions": {
    object (PayloadOptions)
  },
  "notificationEndpoint": {
    object (NotificationEndpoint)
  },
  "state": enum (State),
  "suspensionReason": enum (ErrorType),
  "authority": string,
  "createTime": string,
  "updateTime": string,
  "reconciling": boolean,
  "etag": string,

  // Union field expiration can be only one of the following:
  "expireTime": string,
  "ttl": string
  // End of list of possible types for union field expiration.
}
Поля
name

string

Идентификатор. Имя ресурса подписки.

Формат: subscriptions/{subscription}

uid

string

Только вывод. Уникальный идентификатор подписки, присвоенный системой.

targetResource

string

Обязательно. Неизменяемый. Ресурс Google Workspace, отслеживаемый на наличие событий, отформатированный как полное имя ресурса . Подробнее о целевых ресурсах и поддерживаемых ими событиях см. в разделе Поддерживаемые события Google Workspace .

Пользователь может авторизовать ваше приложение только на создание одной подписки для заданного целевого ресурса. Если ваше приложение попытается создать другую подписку с теми же учётными данными пользователя, запрос вернёт ошибку ALREADY_EXISTS .

eventTypes[]

string

Обязательно. Неупорядоченный список. Входные данные для создания подписки. В противном случае — только выходные данные. Один или несколько типов событий для получения о целевом ресурсе. Отформатировано в соответствии со спецификацией CloudEvents.

Поддерживаемые типы событий зависят от целевого ресурса вашей подписки. Подробнее см. в разделе Поддерживаемые события Google Workspace .

По умолчанию вы также получаете события жизненного цикла вашей подписки . Указывать события жизненного цикла для этого поля не нужно.

Если указать тип события, которого нет для целевого ресурса, запрос вернет код состояния HTTP 400 Bad Request .

payloadOptions

object ( PayloadOptions )

Необязательно. Параметры, определяющие, какие данные следует включить в полезную нагрузку события. Поддерживается только для событий Google Chat.

notificationEndpoint

object ( NotificationEndpoint )

Обязательно. Неизменяемо. Конечная точка, куда подписка отправляет события, например, тему Pub/Sub.

state

enum ( State )

Только вывод. Состояние подписки. Определяет, может ли подписка получать события и доставлять их в конечную точку уведомлений.

suspensionReason

enum ( ErrorType )

Только вывод. Ошибка, приостановившая подписку.

Чтобы повторно активировать подписку, устраните ошибку и вызовите метод subscriptions.reactivate .

authority

string

Только вывод. Пользователь, авторизовавший создание подписки.

Формат: users/{user}

Для пользователей Google Workspace значение {user} — это поле user.id из API каталога.

createTime

string ( Timestamp format)

Только вывод. Время создания подписки.

updateTime

string ( Timestamp format)

Только вывод. Время последнего обновления подписки.

reconciling

boolean

Только вывод. Если true , подписка находится в процессе обновления.

etag

string

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

expiration поля Union. Время истечения срока действия подписки.

Максимальное время истечения срока действия зависит от того, включает ли ваша подписка данные о ресурсах в полезные данные событий (указывается в поле PayloadOptions ):

  • Если полезные данные не содержат данных о ресурсах, то до 7 дней.
  • Если полезные данные включают данные о ресурсах, срок действия подписки может составлять до 4 часов. Если ваша организация Google Workspace предоставляет доступ к ресурсу посредством делегирования на уровне домена , вы можете продлить срок действия подписки до 24 часов.

По истечении срока действия подписки она автоматически удаляется. События жизненного цикла будут поступать в notification_endpoint за 12 часов и за час до истечения срока действия подписки. Подробнее см. в разделе Получение и реагирование на события жизненного цикла .

Чтобы предотвратить истечение срока действия подписки, можно использовать метод UpdateSubscription для продления срока её действия. Подробнее см. в разделе Обновление или продление подписки . expiration может быть только одним из следующих:

expireTime

string ( Timestamp format)

Непустое значение по умолчанию. Временная метка в формате UTC, когда подписка истекает. Всегда отображается на выходе, независимо от того, что использовалось на входе.

ttl

string ( Duration format)

Только ввод. Время жизни (TTL) или продолжительность подписки. Если не указано или равно 0 , используется максимально возможная продолжительность.

Варианты полезной нагрузки

Параметры, определяющие, какие данные включать в полезную нагрузку события. Поддерживается только для событий Google Chat.

JSON-представление 
{
  "includeResource": boolean,
  "fieldMask": string
}
Поля
includeResource

boolean

Необязательно. Включает ли полезная нагрузка события данные об изменившемся ресурсе. Например, для события, в котором было создано сообщение Google Chat, содержит ли полезная нагрузка данные о ресурсе Message . Если false, полезная нагрузка события включает только имя изменившегося ресурса.

fieldMask

string ( FieldMask format)

Необязательно. Если includeResource имеет значение true , список полей, включаемых в полезную нагрузку события. Разделяйте поля запятыми. Например, чтобы включить отправителя и время создания сообщения Google Chat, введите message.sender,message.createTime . Если этот параметр пропущен, полезная нагрузка включает все поля ресурса.

Если указать поле, которого нет для ресурса, система проигнорирует это поле.

NotificationEndpoint

Конечная точка, куда подписка доставляет события.

JSON-представление 
{

  // Union field endpoint can be only one of the following:
  "pubsubTopic": string
  // End of list of possible types for union field endpoint.
}
Поля

endpoint поля объединения.

endpoint может быть только одной из следующих:

pubsubTopic

string

Неизменяемый. Тема Pub/Sub, которая получает события для подписки.

Формат: projects/{project}/topics/{topic}

Тему необходимо создать в том же проекте Google Cloud, где вы создаете эту подписку.

Примечание: API событий Google Workspace использует ключи упорядочивания для удобства последовательных событий. Если в теме Cloud Pub/Sub настроена политика хранения сообщений, исключающая ближайший регион Google Cloud, публикация событий с ключами упорядочивания завершится ошибкой.

Когда тема получает события, они кодируются как сообщения Pub/Sub. Подробнее см. в разделе «Привязка протокола Pub/Sub Google Cloud для CloudEvents» .

Состояние

Возможные состояния подписки.

Перечисления
STATE_UNSPECIFIED Значение по умолчанию. Это значение не используется.
ACTIVE Подписка активна и может получать и доставлять события в свою конечную точку уведомлений.
SUSPENDED Подписка не может получать события из-за ошибки. Чтобы определить ошибку, см. поле suspensionReason .
DELETED Подписка удалена.

Тип ошибки

Возможные ошибки при подписке.

Перечисления
ERROR_TYPE_UNSPECIFIED Значение по умолчанию. Это значение не используется.
USER_SCOPE_REVOKED Авторизующий пользователь отозвал предоставление одной или нескольких областей OAuth. Подробнее об авторизации для Google Workspace см. в статье «Настройка экрана согласия OAuth» .
RESOURCE_DELETED Целевой ресурс для подписки больше не существует.
USER_AUTHORIZATION_FAILURE Пользователь, авторизовавший создание подписки, больше не имеет доступа к целевому ресурсу подписки.
ENDPOINT_PERMISSION_DENIED Приложение Google Workspace не имеет доступа к доставке событий в конечную точку уведомлений вашей подписки.
ENDPOINT_NOT_FOUND Конечная точка уведомления подписки не существует, или конечная точка не найдена в проекте Google Cloud, где вы создали подписку.
ENDPOINT_RESOURCE_EXHAUSTED Конечная точка уведомлений подписки не смогла получить события из-за недостаточной квоты или достижения ограничения по скорости.
OTHER Произошла неопознанная ошибка.

Методы

create

 Создает подписку на Google Workspace.

delete

 Удаляет подписку на Google Workspace.

get

 Получает сведения о подписке Google Workspace.

list

 Список подписок Google Workspace.

patch

 Обновляет или возобновляет подписку на Google Workspace.

reactivate

 Повторно активирует приостановленную подписку на Google Workspace.