此页面由 Cloud Translation API 翻译。

推送通知

本文档介绍了如何在资源发生更改时使用推送通知来通知您的应用。

概览

Admin SDK API 提供推送通知，可让您监控资源更改。您可以使用此功能提升应用的性能。这样，您就可以消除与轮询资源相关的额外网络和计算成本，以确定这些资源是否发生了变化。每当监控的资源发生变化时，Admin SDK API 都会通知您的应用。

如需使用推送通知，您需要执行以下两项操作：

设置接收网址或“网络钩子”回调接收器。
这是一个 HTTPS 服务器，负责处理资源更改时触发的 API 通知消息。
为您要监控的每个资源端点设置通知渠道。
渠道用于指定通知消息的路由信息。在频道设置过程中，您需要指定用于接收通知的特定网址。每当渠道的资源发生变化时，Admin SDK API 都会以 POST 请求的形式向该网址发送一条通知消息。

目前，Admin SDK API 支持更改 Activities 资源。

创建通知渠道

如需请求推送通知，您需要为要监控的每个资源设置通知渠道。设置通知渠道后，如有任何监控的资源发生变化，Admin SDK API 将会通知您的应用。

发出观看请求

每个可监测的 Admin SDK API 资源都有一个关联的 watch 方法，该方法的 URI 格式如下：

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

如需针对特定资源更改的消息设置通知渠道，请向该资源的 watch 方法发送 POST 请求。

每个通知渠道都与特定用户和特定资源（或一组资源）相关联。除非当前用户或服务帐号拥有或有权访问此资源，否则 watch 请求不会成功。

示例

针对 Activity 资源的所有观看请求都采用以下格式：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

您可以使用 userKey、applicationName、eventName 和 filters 参数仅接收特定事件、用户或应用的通知。

注意：为清楚起见，以下示例省略了请求正文。

注意所有管理员活动：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

注意所有文档活动：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

留意特定用户的管理员活动：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

留意特定事件，例如更改用户密码：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

留意特定文档的更改：

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

必要属性

对于每个 watch 请求，您需要提供以下信息：

id 属性字符串，用于唯一标识项目中的这一新通知渠道。我们建议您使用通用唯一标识符 (UUID) 或任何类似的唯一标识符字符串。长度上限：64 个字符。

您设置的渠道 ID 值会在您接收此渠道的每条通知消息的 X-Goog-Channel-Id HTTP 标头中回显。
将 type 属性字符串设置为值 web_hook。
将 address 属性字符串设置为监听和响应此通知渠道的通知的网址。这是您的网络钩子回调网址，必须使用 HTTPS。

请注意，只有在您的网络服务器上安装了有效的 SSL 证书后，Admin SDK API 才能向此 HTTPS 地址发送通知。无效的证书包括：
- 自签发证书
- 由不受信任的来源签发的证书
- 已被撤消的证书
- 主题与目标主机名不匹配的证书。

可选属性

您还可以通过 watch 请求指定以下可选字段：

token 属性，用于指定用作渠道令牌的任意字符串值。您可以将通知渠道令牌用于多种用途。例如，您可以使用令牌验证每条传入消息是否对应于您的应用创建的某个渠道（确保通知不被假冒），或根据此渠道的用途将消息路由到您应用中的正确目的地。长度上限：256 个字符。
在您的应用针对此渠道收到的每条通知消息中，此令牌都会包含在 X-Goog-Channel-Token HTTP 标头中。

如果您使用通知渠道令牌，我们建议您：
- 使用可扩展的编码格式，例如网址查询参数。示例：forwardTo=hr&createdBy=mobile
- 请勿添加 OAuth 令牌等敏感数据。
注意：如果您确实需要发送高度敏感数据，请先确保数据已加密，然后再将其添加到令牌中。
expiration 属性字符串，设置为您希望 Admin SDK API 停止为此通知渠道发送消息的日期和时间的 Unix 时间戳（以毫秒为单位）。

如果渠道有到期时间，则会作为 X-Goog-Channel-Expiration HTTP 标头的值（这次采用人类可读懂的格式）包含在您的应用针对该渠道收到的每条通知消息中。

注意：对于 Admin SDK API，最长到期时间为 21600 秒。如果您未在请求中设置 expiration 属性，则到期时间默认为当前时间之后 21600 秒。

如需详细了解该请求，请参阅 API 参考文档中 Activities 资源的 watch 方法。

观看回复

如果 watch 请求成功创建了通知渠道，则会返回 HTTP 200 OK 状态代码。

手表响应的消息正文会提供您刚刚创建的通知渠道的相关信息，如以下示例所示。

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

除了您在请求中发送的属性外，返回的信息还包含 resourceId 和 resourceUri，用于标识在此通知渠道上监控的资源。

注意：resourceId 属性是资源的版本独立标识符。resourceUri 属性是当前 API 版本上下文中受监控资源的规范 URI，因此是特定于版本的资源。

您可以将返回的信息传递给其他通知渠道操作，例如您想要停止接收通知时。

如需详细了解该响应，请参阅 API 参考文档中的 Activities 资源的 watch 方法。

同步消息

创建新的通知渠道以监控资源后，Admin SDK API 会发送 sync 消息以表明通知已开始。这些消息的 X-Goog-Resource-State HTTP 标头值为 sync。由于网络计时问题，即使您收到 watch 方法响应，也可能收到 sync 消息。

您可以忽略 sync 通知，但您也可以利用它。例如，如果您决定不保留渠道，可以在调用中使用 X-Goog-Channel-ID 和 X-Goog-Resource-ID 值来停止接收通知。您还可以使用 sync 通知进行一些初始化，以便为以后的事件做准备。

Admin SDK API 发送到您的接收网址的 sync 消息的格式如下所示。

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format; present only if channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

同步消息的 X-Goog-Message-Number HTTP 标头值始终为 1。此渠道的后续每条通知都会显示一个大于上一个通知编号的消息，但该编号不会按顺序排列。

续订通知渠道

通知渠道可以设有到期时间，其值由您的请求或任何 Admin SDK API 内部限制或默认值决定（使用限制性更高的值）。该渠道的到期时间（如果有）会作为 Unix 时间戳（以毫秒为单位）包含在 watch 方法返回的信息中。此外，在 X-Goog-Channel-Expiration HTTP 标头中，此渠道收到的每条通知消息都会以人类可读的格式包含失效日期和时间。

目前无法为通知渠道续订。当渠道快要到期时，您必须调用 watch 方法创建一个新渠道。与往常一样，您必须为新渠道的 id 属性使用唯一值。请注意，可能存在同一资源的两个通知渠道处于活动状态的“重叠”时间段。

接收通知

每当监控的资源发生变化时，您的应用都会收到描述更改的通知消息。Admin SDK API 会将这些消息作为 HTTPS POST 请求发送到您指定为此通知渠道的“地址”的网址。

注意：如 API Google 用户代理中所述，这些通知传送 HTTPS 请求会指定 APIs-Google 用户代理并遵循 robots.txt 指令。

了解通知消息格式

所有通知消息都包含一组具有 X-Goog- 前缀的 HTTP 标头。某些类型的通知还可以包含消息正文。

标头

Admin SDK API 向您的接收网址发布的通知消息包含以下 HTTP 标头：

标题	说明
始终显示
`X-Goog-Channel-ID`	您为了标识此通知渠道而提供的 UUID 或其他唯一字符串。
`X-Goog-Message-Number`	用于标识此通知渠道的此消息的整数。对于 `sync` 消息，该值始终为 1。通道上后续每条消息的消息号都会增加，但它们并非按顺序排列。
`X-Goog-Resource-ID`	一个不透明值，用于标识观察到的资源。此 ID 在各个 API 版本中都很稳定。
`X-Goog-Resource-State`	触发通知的新资源状态。可能的值：`sync` 或事件名称。
`X-Goog-Resource-URI`	受监控资源的 API 版本专属标识符。
偶尔会
`X-Goog-Channel-Expiration`	通知渠道到期的日期和时间，以人类可读懂的格式表示。仅在已定义时才存在。
`X-Goog-Channel-Token`	您的应用设置的通知渠道令牌，可用于验证通知的来源。仅在已定义时才存在。

Activity 的通知消息在请求正文中包含以下信息：

属性	说明
`kind`	将其标识为 Activity 资源。值：固定字符串“`admin#reports#activity`”。
`id`	活动记录的唯一标识符。
`id.time`	活动的发生时间。该值采用 ISO 8601 日期和时间格式。时间是完整的日期加时、分、秒，格式为 YYYY-MM-DDThh:mm:ssTZD。例如 2010-04-05T17:30:04+01:00。
`id.uniqueQualifier`	在多个事件相同的情况下使用的唯一限定符。
`id.applicationName`	事件所属的应用名称。可能的值包括：管理员日历云端硬盘群组 groups_enterprise login 移动设备 SAML 令牌用户帐号
`id.customerId`	Google Workspace 帐号的唯一标识符。
`actor`	执行操作的用户。
`actor.callerType`	执行报告中列出的活动的作者类型。在此 API 版本中，`callerType` 是执行了报告中列出的操作的 `USER` 或 OAuth 2LO 实体请求。
`actor.email`	要报告其活动的用户的主电子邮件地址。
`actor.profileId`	用户的唯一 Google Workspace 个人资料 ID。
`ownerDomain`	管理控制台或文档应用的网域所有者。这是受报告事件影响的网域。
`ipAddress`	执行操作的用户的 IP 地址。这是用户在登录 Google Workspace 时获得的互联网协议 (IP) 地址，该地址不一定能反映用户的实际位置。例如，IP 地址可以是用户的代理服务器地址或虚拟专用网 (VPN) 地址。该 API 支持 IPv4 和 IPv6。
`events[]`	报告中的活动事件。
`events[].type`	事件类型。管理员更改的 Google Workspace 服务或功能会在 `type` 属性（标识使用 `eventName` 属性）中标识。
`events[].name`	事件的名称。这是 API 所报告 Activity 的具体名称。每个 `eventName` 都与该 API 整理到特定事件类型的 Google Workspace 服务或功能相关。对于一般的 `eventName` 请求参数：如果未指定 `eventName`，则报告会返回 `eventName` 的所有可能实例。当您请求 `eventName` 时，API 的响应会返回包含该 `eventName` 的所有 Activity。除了所请求的属性外，返回的 activity 可能还具有其他 `eventName` 属性。
`events[].parameters[]`	各种应用的参数值对。
`events[].parameters[].name`	参数的名称。
`events[].parameters[].value`	参数的字符串值。
`events[].parameters[].intValue`	参数的整数值。
`events[].parameters[].boolValue`	参数的布尔值。

示例

Activity 资源事件的通知消息采用以下格式：

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

管理员活动事件示例：

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

回应通知

为了表示成功，您可以返回以下任一状态代码：200、201、202、204 或 102。

如果您的服务使用 Google 的 API 客户端库并返回 500、502、503 或 504，Admin SDK API 将以指数退避算法重试。所有其他返回状态代码都被视为消息失败。

了解 Admin SDK API 通知事件

本部分详细介绍了通过 Admin SDK API 使用推送通知时，您收到的通知消息。

Reports API 推送通知包含两种类型的消息：同步消息和事件通知。消息类型在 X-Goog-Resource-State HTTP 标头中指定。事件通知的可能值与 activities.list 方法的可能值相同。每个应用都有唯一的事件：

停止通知

到期时间是系统自动停止通知的时间。您可以通过在以下网址调用 stop 方法，选择在特定渠道过期之前停止接收通知：

https://www.googleapis.com/admin/reports_v1/channels/stop

此方法要求您至少提供频道的 id 和 resourceId 属性，如以下示例所示。请注意，即使 Admin SDK API 的多种资源类型都有 watch 方法，也只有一个 stop 方法。

只有拥有适当权限的用户才能停止频道。具体而言：

如果渠道是由常规用户帐号创建的，则只有来自同一客户端（由身份验证令牌中的 OAuth 2.0 客户端 ID 标识）的同一用户才能停止该渠道。
如果渠道是由服务帐号创建的，来自同一客户端的任何用户都可以停止渠道。

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}