推送通知

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

概览

Admin SDK API 提供推送通知,让您可以监控 资源的变化您可以利用此功能 部署应用它让您可以消除额外的网络和计算资源, 轮询资源以确定资源是否已更改而产生的费用。 每当受监控的资源发生变化时,Admin SDK API 都会通知您 应用。

如需使用推送通知,您必须完成以下两项操作:

  • 设置接收网址或“webhook”回调接收器。

    这个 是一个 HTTPS 服务器,用于处理 在资源发生更改时触发。

  • 为每个您要部署的资源端点设置一个(通知渠道) 观看。

    渠道指定了通知的路由信息 消息。在频道设置过程中,您必须指明 您希望接收通知每当渠道的资源发生变化时 Admin SDK API 会以 POST 形式发送通知消息, 向该网址发送请求。

目前,Admin SDK API 支持在发生以下情况时发送通知: Activity 资源。

创建通知渠道

如需请求推送通知,您必须设置通知渠道 监控每个您想要监控的资源设置通知渠道后 发现任何受监控的资源时,Admin SDK API 会通知您的应用 更改。

发出监控请求

每个可观察的 Admin SDK API 资源都有一个关联的 watch 方法,并且 URI 的格式如下:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

要为关于更改配置的消息设置通知渠道,请执行以下操作: 请向特定资源发送 POST 请求, watch 方法。

每个通知渠道都与特定用户以及 特定资源(或一组资源)。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.
}

您可以使用 userKeyapplicationNameeventNamefilters 参数仅接收特定事件、用户或应用的通知。

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

监控所有管理员活动:

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。

    请注意,Admin SDK API 能够向 仅当安装了有效的 SSL 证书时,才指定此 HTTPS 地址 。无效的证书包括:

    • 自签发证书
    • 由不受信任的来源签发的证书
    • 已被撤消的证书
    • 证书的主题与目标不匹配 主机名

可选属性

您也可以通过 watch 请求:

  • token 属性,用于指定任意字符串 值用作渠道令牌。您可以使用通知渠道 用于各种用途的令牌。例如,您可以使用 令牌来验证收到的每条消息是否都适用于 应用 - 确保系统不会发出通知 或将邮件转送到 并根据此渠道的用途说明您的应用。长度上限: 256 个字符。

    该令牌包含在 每条通知中包含 X-Goog-Channel-Token HTTP 标头 消息。

    如果您使用通知渠道令牌,我们建议您:

    • 使用可扩展的编码格式,例如网址查询 参数。示例:forwardTo=hr&createdBy=mobile

    • 请勿包含 OAuth 令牌等敏感数据。

  • expiration 属性字符串,设置为 Unix 时间戳 (以毫秒为单位)。 停止为此通知渠道发送消息。

    如果某个渠道有到期时间,则系统会将其添加为 X-Goog-Channel-Expiration HTTP 标头的 格式)。 。

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

观看回复

如果 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.
}

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

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

如需详细了解响应,请参阅 watch 方法。

同步信息

创建用于监控资源的通知渠道后, Admin SDK API 会发送 sync 消息来指明: 开始接收通知。X-Goog-Resource-State HTTP 这些邮件的标头值为 sync。原因:网络 时间问题,可能会收到 sync 消息 您甚至无需收到 watch 方法响应。

您可以放心地忽略 sync 通知,但您可以 也会使用它例如,如果您不想保留 可以使用 X-Goog-Channel-IDX-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 the 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 请求的形式发送到您指定为 此通知的 address 属性

解读通知消息格式

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

标头

Admin SDK API 向您的接收账号发出的通知消息 网址包含以下 HTTP 标头:

标题 说明
始终存在
X-Goog-Channel-ID 您提供的用于标识此 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 事件所属的应用名称。可能的值包括: <ph type="x-smartling-placeholder">
id.customerId Google Workspace 账号的唯一标识符。
actor 执行操作的用户。
actor.callerType 执行报告中列出的活动的作者类型。在此版本的 API 中,callerType 是执行了报告中列出的操作的 USER 或 OAuth 2LO 实体请求。
actor.email 要报告其活动的用户的主电子邮件地址。
actor.profileId 用户的唯一 Google Workspace 个人资料 ID。
ownerDomain 管理控制台或 Google 文档应用的文档所有者的网域。受报告事件影响的网域。
ipAddress 执行操作的用户的 IP 地址。这是用户登录 Google Workspace 时使用的互联网协议 (IP) 地址,不一定能反映用户的实际位置。例如,IP 地址可以是用户的代理服务器地址,也可以是虚拟专用网 (VPN) 地址。该 API 支持 IPv4IPv6
events[] 报告中的活动事件。
events[].type 事件类型。type 属性用于标识管理员更改的 Google Workspace 服务或功能,此属性使用 eventName 属性标识事件。
events[].name 事件名称。这是 API 所报告活动的具体名称。每个 eventName 都与特定的 Google Workspace 服务或功能相关,API 按事件类型整理了相应服务或功能。
适用于一般的 eventName 请求参数: <ph type="x-smartling-placeholder">
    </ph>
  • 如果未指定 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"
        }
      ]
    }
  ]
}

有关通知的操作

如需指示成功,您可以返回以下任一状态代码: 200201202204102

如果您的服务使用 Google 的 API 客户端库 并返回 500502503504(即 Admin SDK API) 使用指数退避算法重试。 所有其他返回状态代码都被视为消息失败。

了解 Admin SDK API 通知事件

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

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

停止通知

expiration 属性用于控制何时自动停止通知。您可以 选择先停止接收特定频道的通知 通过调用 stop 方法过期 以下 URI:

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

此方法要求您至少提供频道的 idresourceId 属性,如 示例。请注意,如果 Admin SDK API 具有几种类型的 具有 watch 方法的资源,只有一个方法 stop 方法。

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

  • 如果频道是由常规用户账号创建的,则只有该账号 来自同一客户端的用户(通过 OAuth 2.0 客户端 ID 来标识, 身份验证令牌)可以停止渠道。
  • 如果渠道是由服务账号创建的,则同一服务账号的任何用户 客户端可以停止该频道。

以下代码示例展示了如何停止接收通知:

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

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