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