REST Resource: subscriptions

• Ресурс: Подписка
  • JSON-представление
• Параметры полезной нагрузки
  • JSON-представление
• Конечная точка уведомления
  • JSON-представление
• Состояние
• Тип ошибки
• Методы

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

Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям.

Подписка на получение событий о ресурсе Google Workspace. Дополнительную информацию о подписках см. в обзоре API Google Workspace Events .

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 из Directory API.
createTime	string ( Timestamp format) Только вывод. Время создания подписки.
updateTime	string ( Timestamp format) Только вывод. Время последнего обновления подписки.
reconciling	boolean Только вывод. Если true , подписка находится в процессе обновления.
etag	string Необязательный. Эта контрольная сумма вычисляется сервером на основе значений других полей и может отправляться в запросах на обновление, чтобы убедиться, что клиент имеет актуальное значение, прежде чем продолжить.
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 Неизменяемый. Тема Cloud Pub/Sub, которая получает события для подписки. Формат: projects/{project}/topics/{topic} Вы должны создать тему в том же проекте Google Cloud, в котором вы создаете эту подписку. Когда тема получает события, они кодируются как сообщения Cloud Pub/Sub. Подробную информацию см. в привязке протокола Google Cloud Pub/Sub для 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 Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Создает подписку на Google Workspace.
delete	Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Удаляет подписку на Google Workspace.
get	Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Получает сведения о подписке на Google Workspace.
list	Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Перечисляет подписки Google Workspace.
patch	Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Обновляет или продлевает подписку на Google Workspace.
reactivate	Предварительная версия для разработчиков: доступна в рамках программы Google Workspace Developer Preview Program , которая предоставляет ранний доступ к определенным функциям. Повторно активирует приостановленную подписку на Google Workspace.