推送通知服务请求和响应标头（Windows 运行时应用）

本主题介绍发送推送通知所需的服务到服务 Web API 和协议。

有关推送通知和 WNS 概念、要求和作的概念性讨论，请参阅 Windows 推送通知服务（WNS）概述 。

请求和接收访问令牌

本部分介绍使用 WNS 进行身份验证时涉及的请求和响应参数。

访问令牌请求

HTTP 请求将发送到 WNS，以对云服务进行身份验证并检索返回的访问令牌。 请求通过安全套接字层 （SSL） 发给 https://login.live.com/accesstoken.srf。

访问令牌请求参数

云服务使用“application/x-www-form-urlencoded”格式在 HTTP 请求正文中提交这些必需参数。 必须确保所有参数都经过 URL 编码。

访问令牌响应

WNS 对云服务进行身份验证，如果成功，则返回“200 OK”，并包括访问令牌。 否则，WNS 使用 OAuth 2.0 协议草案中所述的相应 HTTP 错误代码进行响应。

访问令牌响应参数

如果云服务成功进行身份验证，则会在 HTTP 响应中返回访问令牌。 此访问令牌可在通知请求中使用，直到它过期。 HTTP 响应使用“application/json”媒体类型。

响应代码

示例：

下面显示了成功的身份验证响应示例：

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer",
     "expires_in": 86400
 }

发送通知请求并接收响应

本部分描述 WNS 的 HTTP 请求中用于传递通知以及答复中所涉及的标头。

• 发送通知请求
• 发送通知响应
• 不支持的 HTTP 功能

发送通知请求

发送通知请求时，调用应用通过 SSL 发出 HTTP 请求，该请求会发送到通道统一资源标识符（URI）。 “Content-Length”是必须在请求中指定的标准 HTTP 标头。 所有其他标准标头都是可选的或不支持的。

此外，此处列出的自定义请求标头可用于通知请求。 有些标头是必需的，而另一些标头是可选的。

请求参数

重要说明

• 内容长度和内容类型是发送到客户端的通知中包含的唯一标准 HTTP 标头，无论请求中是否包括其他标准标头。
• 如果不支持该功能，则忽略所有其他标准 HTTP 标头或返回错误。
• 从 2023 年 2 月开始，当设备脱机时，WNS 将仅缓存一个磁贴通知。

授权

授权标头用于指定调用方凭据，遵循 持有者 令牌的 OAuth 2.0 授权方法。

语法格式是由字符串字面量“Bearer”开始，后接一个空格，接着是你的访问令牌。 通过发出上述访问令牌请求来检索此访问令牌。 相同的访问令牌可用于后续通知请求，直到它过期。

此标头是必需的。

Authorization: Bearer <access-token>

X-WNS-Type

这些是 WNS 支持的通知类型。 此标头指示通知的类型以及 WNS 如何处理通知。 通知到达客户端后，将针对此指定类型验证实际有效负载。 此标头是必需的。

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

X-WNS-Cache-Policy

当通知目标设备处于脱机状态时，WNS 将为每个通道 URI 缓存一个徽章通知、一个磁贴和一个 Toast 通知。 默认情况下，不会缓存原始通知，但如果启用了原始通知缓存，则会缓存一个原始通知。 项不会无限期保存在缓存中，将在合理的时间段后删除。 否则，当设备下一次联机时，将传送缓存的内容。

X-WNS-Cache-Policy: cache | no-cache

X-WNS-RequestForStatus

指定响应是否应包括设备状态和 WNS 连接状态。 此标头是可选的。

    X-WNS-RequestForStatus: true | false

X-WNS-Tag

将 标记 标签分配给通知。 当应用选择通知循环时，该标记用于通知队列中磁贴的替换策略。 如果队列中已存在具有此标记的通知，则具有相同标记的新通知将取代该通知。

    X-WNS-Tag: <string value>

X-WNS-TTL

指定通知的 TTL（过期时间）。 这通常不需要，但如果你希望确保通知不会晚于特定时间显示，则可以使用。 TTL 以秒为单位指定，相对于 WNS 接收请求的时间。 指定 TTL 后，设备将不会在该时间后显示通知。 请注意，如果 TTL 太短，则这可能会导致通知根本不显示。 一般情况下，到期时间至少以分钟为单位。

此标头是可选的。 如果未指定任何值，通知不会过期，并且将在正常通知替换方案下替换。

X-WNS-TTL：<integer value>

X-WNS-SuppressPopup

X-WNS-SuppressPopup：true | false

X-WNS-Group

X-WNS-Group：<string value>

X-WNS-Match

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

发送通知响应

WNS 处理通知请求后，它会在响应中发送 HTTP 消息。 本部分讨论可在该响应中找到的参数和标头。

响应参数

X-WNS-Debug-Trace

此标头以字符串的形式返回有用的调试信息。 建议记录此标头以帮助开发人员调试问题。 向 WNS 报告问题时，需要此标头以及 X-WNS-Msg-ID 标头和 MS-CV。

X-WNS-Debug-Trace：<string value>

X-WNS-DeviceConnectionStatus

在通知请求的 X-WNS-RequestForStatus 标头中请求时，此标头会将设备状态返回给调用应用程序。

X-WNS-DeviceConnectionStatus：已连接 | 已断开连接 | 暂时断开连接

X-WNS-Error-Description

此标头提供一个应记录的便于阅读的错误字符串，以帮助进行调试。

X-WNS-Error-Description： <string value>

X-WNS-Msg-ID

此标头用于为调用方提供通知的标识符。 建议记录此header以帮助调试问题。 向 WNS 报告问题时，需要此标头以及 X-WNS-Debug-Trace 和 MS-CV。

X-WNS-Msg-ID：<string value>

X-WNS-Status

此标头描述 WNS 如何处理通知请求。 这可以使用，而不是将响应代码解释为成功或失败。

X-WNS-Status：已收到 | 已丢弃 | 通道节流

MS-CV

此标头提供与主要用于调试的请求相关的相关向量。 如果请求中提供了 CV，则 WNS 将使用该值；否则，WNS 将生成一个 CV 并进行回复。 向 WNS 报告问题时，需要此标头以及 X-WNS-Debug-Trace 和 X-WNS-Msg-ID 标头。

MS-CV：<string value>

响应代码

每个 HTTP 消息都包含其中一个响应代码。 WNS 建议开发人员记录响应代码以用于调试。 当开发人员向 WNS 报告问题时，需要提供响应代码和标头信息。

不支持的 HTTP 功能

WNS Web 接口支持 HTTP 1.1，但不支持以下功能：

• 分块
• 管道处理 （POST 不是幂等的）
• 尽管受支持，但开发人员应禁用 Expect-100，因为发送通知时会引入延迟。