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

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

Поле Union expiration . Время, когда истекает срок действия подписки.

Максимальное время истечения срока действия зависит от того, включает ли ваша подписка данные о ресурсах в полезные данные событий (указывается в поле 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 . Если пропущено, полезная нагрузка включает все поля для ресурса.

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

УведомлениеКонечная точка

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

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 Workspace Events использует ключи упорядочения для преимуществ последовательных событий. Если тема Cloud Pub/Sub имеет политику хранения сообщений, настроенную на исключение ближайшего региона Google Cloud, публикация событий с ключами упорядочения завершится ошибкой.

Когда тема получает события, события кодируются как сообщения Pub/Sub. Подробности см. в Google Cloud Pub/Sub Protocol Binding для 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.