推送通知

必要属性

每个 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 标头的 格式）。 。

观看回复

如果 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，用于标识在此通知渠道上正在监控的资源。

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

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

同步信息

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

您可以放心地忽略 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 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 属性。请注意，当同一资源的两个通知渠道都处于活跃状态时，可能会出现“重叠”时间段。

解读通知消息格式

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

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 方法相同。每个应用都有独特的事件：

• 管理员
• calendar
• 云端硬盘
• 群组
• login
• 移动设备
• SAML
• 令牌
• user_accounts