推送通知服务请求和响应头（Windows 运行时应用）
[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅 最新文档 ]
此主题介绍了服务到服务的 Web API 以及发送推送通知所需的协议。
有关推送通知和 WNS 概念、要求以及操作的概念讨论，请参阅 Windows 推送通知服务 (WNS) 概述。
请求和接收访问令牌
本部分介绍使用 WNS 进行验证时所涉及的请求参数和响应参数。
访问令牌请求
将 HTTP 请求发送至 WNS 以对云服务进行验证，然后反过来检索访问令牌。通过使用安全套接字层 (SSL) 将请求发布至以下完全限定的域名 (FQDN)。
https://login.live.com/accesstoken.srf
访问令牌请求参数
云服务在 HTTP 请求正文中提交了这些所需参数，采用的格式为“application/x-www-form-urlencoded”。必须确保所有参数都进行 URL 编码。
| 参数 | 必需/可选 | 描述 |
|---|---|---|
| grant_type | 必需 | 必须设置为“client_credentials”。 |
| client_id | 必需 | 向 Windows 应用商店注册应用时已分配的云服务程序包安全标识符 (SID)。 |
| client_secret | 必需 | 向 Windows 应用商店注册应用时已分配的云服务密钥。 |
| 作用域 | 必需 | 必须设置为：
|
访问令牌响应
WNS 对云服务进行验证，如果成功，会使用“200 OK”（包括访问令牌）进行响应。否则，WNS 会使用相应的 HTTP 错误代码（如 OAuth 2.0 协议草案中所述）进行响应。
访问令牌响应参数
如果云服务成功验证，则会在 HTTP 响应中返回访问令牌。此访问令牌可用于通知请求中，直至该令牌过期。HTTP 响应使用“application/json”媒体类型。
| 参数 | 必需/可选 | 描述 |
|---|---|---|
| access_token | 必需 | 云服务在发送通知时使用的访问令牌。 |
| token_type | 可选 | 始终作为“bearer”返回。 |
响应代码
| HTTP 响应代码 | 描述 |
|---|---|
| 200 OK | 请求已成功。 |
| 400 错误的请求 | 验证已失败。请参阅 OAuth 草案征求意见文档 (RFC) 了解响应参数。 |
示例
以下显示了成功验证响应示例：
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Length: 422
Content-Type: application/json
{
"access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=",
"token_type":"bearer"
}
发送通知请求和接收响应
此部分介绍了将 HTTP 请求发送至 WNS 以传递通知时所涉及的头以及回复时所涉及的头。
- 发送通知请求
- 发送通知响应
- 不受支持的 HTTP 功能
发送通知请求
调用应用发送通知请求时，会通过 SSL 发出 HTTP 请求，将该请求发送至信道统一资源标识符 (URI)。"Content-Length" 是标准的 HTTP 标头，必须在请求中指定。所有其他标准标头可选，或者不受支持。
另外，此处所列的自定义请求头可用在通知请求中。某些头必需，而其他头可选。
请求参数
| 头名称 | 必需/可选 | 描述 |
|---|---|---|
| “授权” | 必需 | 标准 HTTP 授权头用于对通知请求进行验证。云服务在此头中提供了其访问令牌。 |
| Content-Type | 必需 | 标准 HTTP 授权头。对于 Toast、磁贴以及锁屏提醒通知，此标头应设置为“text/xml”。对于原始通知，此标头应设置为“application/octet-stream”。 |
| Content-Length | 必需 | 表示请求负载大小的标准 HTTP 授权头。 |
| X-WNS-Type | 必需 | 定义负载中的通知类型：磁贴、Toast、锁屏提醒或原始。 |
| X-WNS-Cache-Policy | 可选 | 启用或禁用通知缓存。此标头仅应用于磁贴、锁屏提醒和原始通知。 |
| X-WNS-RequestForStatus | 可选 | 通知响应中的请求设备状态和 WNS 连接状态。 |
| X-WNS-Tag | 可选 | 用于为通知提供识别标签、用作支持通知队列的磁贴的字符串。此头仅应用于磁贴通知。 |
| X-WNS-TTL | 可选 | 指定生存时间 (TTL) 的整数值（用秒数表示）。 |
| X-WNS-SuppressPopup | 可选 | 仅限 Windows Phone：直接将 Toast 通知传递到操作中心，无需引发 Toast 本身。 |
| X-WNS-Group | 可选 | 仅限 Windows Phone：与 X-WNS-Tag 标头一起使用以在操作中心中为通知分组。 |
| X-WNS-Match | 情境上需要 | 仅限 Windows Phone：当通过 HTTP DELETE 方法从操作中心删除 Toast 通知时需要标识该目标。 |
重要说明
- Content-Length 和 Content-Type 为包含在传递给客户端的通知中仅有的标准 HTTP 头，不论其他标准头是否包含在请求中。
- 忽略所有其他标准 HTTP 头，或者如果不支持该功能，则返回错误。
“授权”
授权标头用于指定调用方的凭据，跟在 bearer 令牌的 OAuth 2.0 授权方法之后。
语法由以下内容组成：字符串文字“Bearer”，后面是空格，再后面是你的访问令牌。通过发布以上所述的访问令牌请求检索此访问令牌。同一访问令牌可用于后续通知请求中，直至该令牌过期。
此标头是必需的。
Authorization: Bearer <access-token>
X-WNS-Type
这些是 WNS 支持的通知类型。此头表示通知类型以及 WNS 处理该通知时应采用的方式。当通知到达客户端之后，针对此指定的类型验证实际的负载。此标头是必需的。
X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
| 值 | 描述 |
|---|---|
| WNS/锁屏提醒 | 在磁贴上创建锁屏提醒覆盖的通知。包含在通知请求中的 Content-Type 标头应设置为“text/xml”。 |
| WNS/磁贴 | 更新磁贴内容的通知。包含在通知请求中的 Content-Type 标头应设置为“text/xml”。 |
| WNS/Toast | 在客户端上引发 Toast 的通知。包含在通知请求中的 Content-Type 标头应设置为“text/xml”。 |
| WNS/原始 | 可包含自定义负载且直接传递到应用的通知。包含在通知请求中的 Content-Type 标头应设置为“application/octet-stream”。 |
X-WNS-Cache-Policy
当通知目标设备处于脱机状态时，WNS 会为每个应用缓存一个锁屏提醒通知和一个磁贴通知。如果为应用启用了通知循环，则 WNS 至多会缓存 5 个磁贴通知。默认情况下，不会缓存原始通知，但如果启用了原始通知缓存，则将会缓存一个原始通知。项不会无限期保留在缓存中，它们会在一段适度长的时间后丢弃。否则，当设备下次联机时，会传递缓存内容。
此标头是可选项，且仅应在这样的情况下使用：云服务希望覆盖默认缓存行为。
X-WNS-Cache-Policy: cache | no-cache
| 值 | 描述 |
|---|---|
| 缓存 | 默认值。如果用户处于脱机状态，则将会缓存通知。这是磁贴通知和锁屏提醒通知的默认设置。 |
| no-cache | 如果用户处于脱机状态，则不会缓存通知。这是原始通知的默认设置。 |
X-WNS-RequestForStatus
指定响应是否应包含设备状态和 WNS 连接状态。此标头是可选的。
X-WNS-RequestForStatus: true | false
| 值 | 描述 |
|---|---|
| true | 返回响应中的设备状态和通知状态。 |
| false | 默认值。请勿返回设备状态和通知状态。 |
X-WNS-Tag
向通知分配 tag 标签。当应用已选择通知循环时，通知队列中的磁贴的替换策略中会使用标记。如果该队列中已存在带有此标记的通知，则带有相同标记的新通知会取代其位置。
注意 此标头为可选且仅在发送磁贴通知时使用。
注意 对于 Windows Phone 应用商店应用，X-WNS-Tag 标头可与 X-WNS-Group 标头一起使用以允许带有相同标记的多个通知在操作中心中显示。
X-WNS-Tag: <string value>
| 值 | 描述 |
|---|---|
| 字符串值 | 不超过 16 个字符的字母数字字符串。 |
X-WNS-TTL
为通知指定 TTL（过期时间）。通常情况下不需要使用此标头，但如果要确保通知在特定时间之后不显示，可以使用此标头。TTL 以秒为单位进行指定，且与 WNS 接收请求的时间相关。如果指定了 TTL，则此后设备将不会显示通知。注意，如果 TTL 太短，则这样可能会导致根本不会显示通知。通常，过期时间的量度单位至少为分钟。
此标头是可选的。如果未指定值，则通知将不会过期，并且会按照正常通知更换方案进行替换。
X-WNS-TTL: <integer value>
| 值 | 描述 |
|---|---|
| 整数值 | WNS 接收请求后的通知生存期跨度（以秒为单位）。 |
X-WNS-SuppressPopup
注意 对于 Windows Phone 应用商店应用，可以选择隐藏 Toast 通知的 UI，而不是将该通知直接发送到操作中心。这让你的通知可以在无提示的情况下传递，对于不太紧急的通知可能是较优选项。此标头为可选且仅在 Windows Phone 频道上使用。如果你在 Windows 频道上包括此标头，将删除你的通知，并且你将收到来自 WNS 的错误响应。
X-WNS-SuppressPopup: true | false
| 值 | 描述 |
|---|---|
| true | 将 Toast 通知直接发送到操作中心；不要引发 Toast UI。 |
| false | 默认值。引发 Toast UI 以及将通知添加到操作中心。 |
X-WNS-Group
注意 Windows Phone 应用商店应用的操作中心仅可在带有相同标记的多个 Toast 通知标记为属于不同组时显示它们。例如，请考虑食谱应用。每个食谱将由标记标识。包含对该食谱的评论的 Toast 将拥有该食谱的标记，但它是一个评论组标签。包含对该食谱的分级的 Toast 仍然将拥有该食谱的标记，但将有分级组标记。这两个不同的组标签将允许两种 Toast 通知同时在操作中心中出现。此标头为可选。
X-WNS-Group: <string value>
| 值 | 描述 |
|---|---|
| 字符串值 | 不超过 16 个字符的字母数字字符串。 |
X-WNS-Match
注意 与 HTTP DELETE 方法一起使用以从 Windows Phone 应用商店应用的操作中心删除特定的 Toast、一组 Toast（按标记或组）或所有 Toast。此标头可指定组、标记，或同时指定两者。HTTP DELETE 通知请求中需要此标头。将忽略此通知请求包含的任何负载。
X-WNS-Match: type:wns/toast;group=<string value>;tag=<string value> | type:wns/toast;group=<string value> | type:wns/toast;tag=<string value> | type:wns/toast;all
| 值 | 描述 |
|---|---|
| type:wns/toast;group=<string value>;tag=<string value> | 删除带有指定标记和组标签的单个通知。 |
| type:wns/toast;group=<string value> | 删除所有带有指定组标签的通知。 |
| type:wns/toast;tag=<string value> | 删除所有带有指定标记的通知。 |
| type:wns/toast;all | 从操作中心清除应用的所有通知。 |
发送通知响应
当 WNS 处理通知请求后，它会发送 HTTP 响应消息。此部分介绍了可在该响应中找到的参数和头。
响应参数
| 头名称 | 必需/可选 | 描述 |
|---|---|---|
| X-WNS-Debug-Trace | 可选 | 报告问题时应记录用于帮助解决问题的调试信息。 |
| X-WNS-DeviceConnectionStatus | 可选 | 设备状态，仅当通过 X-WNS-RequestForStatus 头在通知请求中请求时返回。 |
| X-WNS-Error-Description | 可选 | 应记录用于帮助调试的人工可读错误。 |
| X-WNS-Msg-ID | 可选 | 通知的唯一标识符，用于调试目的。报告问题时，应记录此信息以有助于故障诊断。 |
| X-WNS-Status | 可选 | 指示 WNS 是否成功接收通知并处理通知。报告问题时，应记录此信息以有助于故障诊断。 |
X-WNS-Debug-Trace
此头会返回作为字符串的有用调试信息。建议记录此头以有助于开发者调试问题。向 WNS 报告问题时，需要提供此头连同 X-WNS-Msg-ID 头。
X-WNS-Debug-Trace: <string value>
| 值 | 描述 |
|---|---|
| 字符串值 | 字母数字字符串。 |
X-WNS-DeviceConnectionStatus
如果在通知请求的 X-WNS-RequestForStatus 头中请求，则此头会将设备状态返回至调用应用程序。
X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected
| 值 | 描述 |
|---|---|
| 已连接 | 设备处于联机状态且已连接至 WNS。 |
| 已断开连接 | 设备处于脱机状态且未连接至 WNS。 |
| 已临时连接 | 设备临时断开与 WNS 的连接，例如，当 3G 连接断开或便携式计算机上的无线交换机被关闭。通知客户端平台将此视为临时中断，而不是故意断开连接。 |
X-WNS-Error-Description
此头会提供应记录用于帮助调试的人工可读错误字符串。
X-WNS-Error-Description: <string value>
| 值 | 描述 |
|---|---|
| 字符串值 | 字母数字字符串。 |
X-WNS-Msg-ID
此头用于为调用方提供通知标识符。建议记录此头以有助于调试问题。向 WNS 报告问题时，需要提供此头连同 X-WNS-Debug-Trace 头。
X-WNS-Msg-ID: <string value>
| 值 | 描述 |
|---|---|
| 字符串值 | 不超过 16 个字符的字母数字字符串。 |
X-WNS-Status
此头介绍了 WNS 处理通知请求的方式。可以使用此头，但不是用于将响应代码解释为成功还是失败。
X-WNS-Status: received | dropped | channelthrottled
| 值 | 描述 |
|---|---|
| 已接收 | WNS 已接收并处理通知。 注意 这并不能保证设备会收到通知。
|
| 已丢弃 | 通知已被显式丢弃，原因是出现错误，或客户端已显式拒绝这些通知。如果设备处于脱机状态，则还会丢弃 Toast 通知。 |
| channelthrottled | 通知已被丢弃，原因是应用服务器已超出此特定信道的速率限制。 |
响应代码
每个 HTTP 消息都包含这些响应代码中的一个响应代码。WNS 建议开发者记录响应代码以便用于调试。当开发者向 WNS 报告问题时，要求他们提供响应代码和头信息。
| HTTP 响应代码 | 描述 | 建议的操作 |
|---|---|---|
| 200 OK | WNS 已接收通知。 | 不需要任何信息。 |
| 400 错误的请求 | 一个或多个头指定错误或与其他头发生冲突。 | 记录请求的详细信息。检查你的请求并与此文档进行比较。 |
| 401 未授权 | 云服务未提供有效的验证票据。OAuth 票据可能无效。 | 请求有效的访问令牌，方法是对使用访问令牌请求的云服务进行验证。 |
| 403 已禁止 | 未授权云服务将通知发送至此 URI，即便这些通知经过验证。 | 请求中提供的访问令牌与请求信道 URI 的应用的凭据不匹配。确保应用清单中的包名称与提供给仪表板中应用的云服务凭据匹配。 |
| 404 未找到 | 信道 URI 无效或 WNS 无法识别该 URI。 | 记录请求的详细信息。不将以后的通知发送至此信道；发送至此地址的通知将失败。 |
| 405 方法不允许 | 无效方法（GET、CREATE）；仅允许 POST（Windows 或 Windows Phone）或 DELETE（仅限 Windows Phone）。 | 记录请求的详细信息。切换到使用 HTTP POST。 |
| 406 无法接受 | 云服务已超出其中止值。 | 记录请求的详细信息。降低发送通知的速率。 |
| 410 不存在 | 信道已过期。 | 记录请求的详细信息。请勿将以后的通知发送至此信道。让应用请求新的通道 URI。 |
| 413 请求实体太大 | 通知负载超出 5000 字节大小限制。 | 记录请求的详细信息。检查负载以确保该负载位于大小限制值之内。 |
| 500 内部服务器错误 | 内部故障已导致通知传递失败。 | 记录请求的详细信息。通过开发人员论坛报告此问题。 |
| 503 服务不可用 | 服务器当前无法使用。 | 记录请求的详细信息。通过开发人员论坛报告此问题。 |
有关特定响应代码的疑难解答详细信息，请参阅磁贴、Toast 和锁屏提醒通知疑难解答。另请参阅 COM Error Codes (WPN, MBN, P2P, Bluetooth)。
不受支持的 HTTP 功能
WNS Web 接口支持 HTTP 1.1，但不支持以下功能：
- 区块
- 流水线处理（POST 不是幂等）
- 尽管支持，但开发人员还是应该禁用 Expect-100，因为发送通知时它会引入延迟。