此页面由 Cloud Translation API 翻译。

推送通知

本文档介绍了如何使用推送通知，以便在资源发生变化时通知您的应用。

概览

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

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

设置接收网址或“webhook”回调接收器。
这是一个 HTTPS 服务器，用于处理在资源发生更改时触发的 API 通知消息。
为每个您要部署的资源端点设置一个（通知渠道）观看。
渠道用于指定通知消息的路由信息。在渠道设置过程中，您必须指明要接收通知的具体网址。每当渠道的资源发生变化时 Directory API 会以 POST 形式发送通知消息，向该网址发送请求。

目前，Directory API 支持针对 Users 资源的更改发送通知。

创建通知渠道

如需请求推送通知，您必须设置通知渠道监控每个您想要监控的资源设置通知渠道后目录 API 在发现任何受监控的资源时更改。

发出观看请求

每个可监控的 Directory API 资源都有一个关联的 watch 方法，其 URI 的格式如下：

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

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

每个通知渠道都与特定用户以及特定资源（或一组资源）。watch 请求除非当前用户或服务账号拥有此资源或有权访问此资源。

示例

针对单个网域的 User 资源的所有监控请求都具有以下通用格式：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

使用 domain 和 event 参数指定您要接收哪个网域和哪类事件的相关通知。

针对客户用户资源的所有监视请求都采用通用形式：

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

您可以使用 customer 和 event 参数来指定客户 Google 账号的唯一 ID，以及您希望接收与哪种类型的事件相关的通知。

event 的可能值包括：

add：用户创建的事件
delete：用户删除事件
makeAdmin：用户管理员状态更改事件
undelete：用户取消删除事件
update：用户更新了事件

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

监控网域 mydomain.com 中用户创建的事件：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

监控客户 my_customer 的用户创建事件：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

必要属性

在每个 watch 请求中，您都必须提供以下字段：

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

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

请注意，Directory API 可以将通知发送到仅当安装了有效的 SSL 证书时，才指定此 HTTPS 地址。无效的证书包括：
- 自签发证书
- 由不受信任的来源签发的证书
- 已被撤消的证书
- 证书的主题与目标主机名不匹配。

可选属性

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

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

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

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

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

观看回复

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

监视器响应的正文会提供有关您刚刚创建的通知渠道的信息，如以下示例所示。

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

注意：resourceId 属性是与版本无关的稳定标识符。resourceUri 属性是当前 API 版本上下文中被监控资源的规范 URI，因此它因版本而异。

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

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

同步消息

创建用于监控资源的通知渠道后，Directory API 会发送 sync 消息，以指示通知即将开始。这些消息的 X-Goog-Resource-State HTTP 标头值为 sync。原因：网络时间问题，可能会收到 sync 消息您甚至无需收到 watch 方法响应。

您可以放心地忽略 sync 通知，但您可以也会使用它例如，如果您决定不想保留该渠道，可以在调用中使用 X-Goog-Channel-ID 和 X-Goog-Resource-ID 值来停止接收通知。您还可以使用 sync 通知执行一些初始化操作，为后续事件做好准备。

Directory 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 的标头值。此渠道的每条后续通知都有即使邮件和聊天消息编号相同，不依序。

续订通知渠道

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

目前，没有自动续订通知渠道的方法。当某个渠道即将过期时，您必须调用 watch 方法将其替换为新渠道。与往常一样，您必须为新频道的 id 属性。请注意，当同一资源的两个通知渠道都处于活跃状态时，可能会出现“重叠”时间段。

接收通知

每当被监控的资源发生变化时，您的应用都会收到一条描述相应更改的通知消息。Directory API 会将这些消息作为 HTTPS POST 请求发送到您为此通知渠道指定的 address 属性网址。

注意：通知传送 HTTPS 请求将用户代理指定为 APIs-Google 并遵循 robots.txt 中的指令指令，如 Google 用户代理。

解读通知消息格式

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

标头

Directory 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`	由您的应用设置的通知渠道令牌，可用于验证通知来源。仅当。

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

属性	说明
`kind`	将此标识为 User 资源。值：固定字符串“`admin#directory#user`”。
`id`	用户资源的唯一标识符。
`etag`	通知消息的 ETag。不同于“User”资源的 ETag。
`primaryEmail`	用户的主电子邮件地址。

示例

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

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

用户删除事件示例：

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

有关通知的操作

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

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

停止通知

expiration 属性用于控制何时自动停止显示通知。您可以选择在特定渠道过期之前停止接收该渠道的通知，方法是调用以下 URI 中的 stop 方法：

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

此方法要求您至少提供频道的 id 和 resourceId 属性，如示例。请注意，如果 Directory API 有多个具有 watch 方法的资源类型，则只有一个 stop 方法。

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

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

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

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

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