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,

  "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 云端硬盘事件。
notificationEndpoint

object (NotificationEndpoint)

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

enum (State)

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

enum (ErrorType)

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

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

string

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

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

格式：users/{user}

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

当 Chat 应用授权订阅时，系统只会填充 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 字段。

格式：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 表示法 
{

  "pubsubTopic": string
}
字段

联合字段 endpoint。

endpoint 只能是下列其中一项：
pubsubTopic

string

不可变。接收订阅事件的 Pub/Sub 主题。

格式：projects/{project}/topics/{topic}

您必须在创建此订阅的同一 Google Cloud 项目中创建该主题。

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

当主题接收事件时，事件会编码为 Pub/Sub 消息。如需了解详情，请参阅 Google Cloud Pub/Sub Protocol Binding for 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 订阅。