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 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} 值为 Directory API 中的 user.id 字段。

createTime

string (Timestamp format)

仅限输出。创建订阅的时间。

updateTime

string (Timestamp format)

仅限输出。上次更新订阅的时间。

reconciling

boolean

仅限输出。如果为 true,则表示订阅正在更新。

etag

string

可选。此校验和由服务器根据其他字段的值计算,并且可能会根据更新请求发送,以确保客户端在继续操作之前拥有最新的值。

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

最长到期时间取决于您的订阅是否在事件载荷(在 PayloadOptions 字段中指定)中包含资源数据:

  • 如果载荷省略了资源数据,最多 7 天。
  • 如果载荷包含资源数据,则最长为 4 小时。如果您的 Google Workspace 组织通过全网域授权方式授予对资源的访问权限,那么您可以将订阅的有效期延长至最长 24 小时。

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

为防止订阅过期,您可以使用 UpdateSubscription 方法延长其到期日期。有关详情,请参阅更新或续订订阅expiration 只能是下列其中一项:

expireTime

string (Timestamp format)

非空默认值。订阅到期时的时间戳(世界协调时间)。无论输入源使用了什么内容,始终在输出中显示。

ttl

string (Duration format)

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

PayloadOptions

有关要在事件载荷中包含哪些数据的选项。仅支持 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。如果省略,载荷将包含资源的所有字段。

如果为该资源指定了不存在的字段,系统会忽略该字段。

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

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

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

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

当主题收到事件时,这些事件会被编码为 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 同意屏幕
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 订阅。