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,

  "driveOptions": {
    object (DriveOptions)
  }
  "userAuthority": string,
  "serviceAccountAuthority": string
  "expireTime": string,
  "ttl": string
}
Поля
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 )

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

Поле объединения 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 на поле профсоюза. Время истечения срока действия подписки.

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

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

Подробности см. в разделе «Типы событий Google Drive» .

PayloadOptions

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

Если вы укажете поле, которого нет в ресурсе, система проигнорирует это поле.

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

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

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

  "pubsubTopic": string
}
Поля

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

endpoint может использоваться только один из следующих вариантов:

pubsubTopic

string

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

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

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

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

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

Состояние

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

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

ErrorType

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

Перечисления
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.
,

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

Подписка на получение событий, связанных с ресурсом 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,

  "driveOptions": {
    object (DriveOptions)
  }
  "userAuthority": string,
  "serviceAccountAuthority": string
  "expireTime": string,
  "ttl": string
}
Поля
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 )

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

Поле объединения 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 на поле профсоюза. Время истечения срока действия подписки.

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

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

Подробности см. в разделе «Типы событий Google Drive» .

PayloadOptions

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

Если вы укажете поле, которого нет в ресурсе, система проигнорирует это поле.

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

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

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

  "pubsubTopic": string
}
Поля

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

endpoint может использоваться только один из следующих вариантов:

pubsubTopic

string

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

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

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

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

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

Состояние

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

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

ErrorType

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

Перечисления
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.