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 subscription_options can be only one of the following:
  "driveOptions": {
    object (DriveOptions)
  }
  // End of list of possible types for union field subscription_options.

  // Union field authority_info can be only one of the following:
  "userAuthority": string,
  "serviceAccountAuthority": string
  // End of list of possible types for union field authority_info.

  // 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 и Google Drive.

notificationEndpoint

object ( NotificationEndpoint )

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

state

enum ( State )

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

suspensionReason

enum ( ErrorType )

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

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

authority

string

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

Когда пользователь авторизует подписку, это поле и поле userAuthority имеют одинаковое значение, а формат следующий:

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

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

Когда приложение чата авторизует подписку, заполняется только поле serviceAccountAuthority , а это поле остается пустым.

createTime

string ( Timestamp format)

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

updateTime

string ( Timestamp format)

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

reconciling

boolean

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

etag

string

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

Поле объединения subscription_options . Дополнительные параметры подписки доступны для определенных целевых ресурсов для подписок Google Workspace. subscription_options может быть только одним из следующих:
driveOptions

object ( DriveOptions )

Необязательно. Функции, которые поддерживаются только для подписок на ресурсы Диска.

Поле объединения authority_info . Идентификатор, авторизовавший создание подписки. authority_info может быть только одним из следующих:
userAuthority

string

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

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

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

serviceAccountAuthority

string

Только выходные данные. Учётная запись службы, использованная для авторизации создания подписки. Эта учётная запись службы должна принадлежать тому же проекту Google Cloud, где вы создаёте эту подписку.

Формат: projects/{projectId}/serviceAccounts/{service_account_id}

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

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

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

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

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

expireTime

string ( Timestamp format)

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

ttl

string ( Duration format)

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

DriveOptions

Дополнительные поддерживаемые параметры обслуживания событий Drive.

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

boolean

Необязательно. Неизменяемо. Для подписок на события Google Диска: получать ли события о файлах Диска, являющихся дочерними по отношению к целевой папке или общему диску.

  • Если false , подписка получает только события об изменениях в папке или общем диске, указанных как targetResource .
  • Если true , поле mimeType ресурса file должно быть установлено на application/vnd.google-apps.folder .

Подробную информацию см. в разделе Типы событий Google Диска .

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

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

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» .
APP_SCOPE_REVOKED Администратор домена отменил предоставление одной или нескольких областей OAuth для приложения.
RESOURCE_DELETED Целевой ресурс для подписки больше не существует.
USER_AUTHORIZATION_FAILURE Пользователь, авторизовавший создание подписки, больше не имеет доступа к целевому ресурсу подписки.
APP_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.