REST Resource: subscriptions

资源：订阅

用于接收 Google Workspace 资源相关事件的订阅。如需详细了解订阅，请参阅 Google Workspace Events API 概览。

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 云端硬盘活动。
notificationEndpoint

object (NotificationEndpoint)

必需。不可变。订阅传送事件的端点，例如 Pub/Sub 主题。
state

enum (State)

仅限输出。订阅的状态。确定订阅是否可以接收事件并将其传递到通知端点。
suspensionReason

enum (ErrorType)

仅限输出。导致订阅暂停的错误。

如需重新激活订阅，请解决相应错误并调用 subscriptions.reactivate 方法。
authority

string

仅限输出。授权创建订阅的用户。

当用户授权订阅时，此字段和 userAuthority 字段具有相同的值，格式为：

格式：users/{user}

对于 Google Workspace 用户，{user} 值是 Directory API 中的 user.id 字段。

当聊天应用授权订阅时，系统仅会填充 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} 值是 Directory API 中的 user.id 字段。

格式：users/{user}
serviceAccountAuthority

string

仅限输出。用于授权创建订阅的服务账号。此服务账号必须归您创建相应订阅的 Google Cloud 项目所有。

格式：projects/{projectId}/serviceAccounts/{service_account_id}

联合字段 expiration。订阅到期的时间。

最长过期时间取决于您的订阅是否包含事件载荷中的资源数据（在 PayloadOptions 字段中指定）：

  • 如果载荷省略了资源数据，则为最多 7 天。
  • 如果载荷包含资源数据，则为最多 4 小时。如果您的 Google Workspace 组织通过网域范围的委托授予对资源的访问权限，您可以将订阅的到期时间延长最多 24 小时。

订阅到期后，系统会自动将其删除。您会在订阅到期前 12 小时和 1 小时收到生命周期事件。notification_endpoint如需了解详情，请参阅接收和响应生命周期事件。

如需防止订阅过期，您可以使用 UpdateSubscription 方法来延长其到期日期。如需了解详情，请参阅更新或续订订阅。expiration 只能是下列其中一项：
expireTime

string (Timestamp format)

非空默认值。订阅到期时的时间戳（世界协调时间）。无论输入中使用了什么内容，输出中始终都会显示此时间戳。
ttl

string (Duration format)

仅限输入。订阅的存留时间 (TTL) 或时长。如果未指定或设置为 0，则使用尽可能长的时长。

DriveOptions

用于传送云端硬盘事件的其他受支持选项。

JSON 表示法 
{
  "includeDescendants": boolean
}
字段
includeDescendants

boolean

可选。不可变。对于 Google 云端硬盘活动的订阅，是否接收有关目标文件夹或共享云端硬盘的子级云端硬盘文件的事件。

  • 如果值为 false，则订阅仅接收有关指定为 targetResource 的文件夹或共享云端硬盘的更改事件。
  • 如果为 true，则必须将 file 资源的 mimeType 字段设置为 application/vnd.google-apps.folder。

如需了解详情，请参阅 Google 云端硬盘事件类型。

PayloadOptions

有关要在事件载荷中包含哪些数据的选项。仅支持 Google Chat 和 Google 云端硬盘活动。

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 项目中创建主题。

注意：Google Workspace Events API 使用排序键来处理顺序事件。如果 Cloud Pub/Sub 主题配置了消息存储政策以排除最近的 Google Cloud 地区，则发布带有排序键的事件将会失败。

当主题收到事件时，这些事件会编码为 Pub/Sub 消息。如需了解详情，请参阅 CloudEvents 的 Google Cloud Pub/Sub 协议绑定。

州

订阅可能具有的状态。

枚举
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 订阅。