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