此页面由 Cloud Translation API 翻译。

REST Resource: subscriptions

资源：订阅
- JSON 表示法
PayloadOptions <ph type="x-smartling-placeholder">
- JSON 表示法
NotificationEndpoint <ph type="x-smartling-placeholder">
- JSON 表示法
状态
ErrorType
方法

资源：订阅

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

JSON 表示法

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,
  "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`。如果省略，载荷将包含资源的所有字段。如果为该资源指定了不存在的字段，系统会忽略该字段。

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 协议绑定。

联合字段 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 订阅。

REST Resource: subscriptions

资源：订阅

PayloadOptions

NotificationEndpoint

州

ErrorType

方法

`create`

`delete`

`get`

`list`

`patch`

`reactivate`