REST Resource: subscriptions

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

Подписка на получение событий о ресурсе 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.

delete

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

get

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

list

 Перечисляет подписки Google Workspace.

patch

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

reactivate

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

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

Подписка на получение событий о ресурсе 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.

delete

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

get

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

list

 Перечисляет подписки Google Workspace.

patch

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

reactivate

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