推送通知服务请求和响应标头（Windows 运行时应用）
本主题介绍发送推送通知时所需的服务到服务 Web API 和协议。
有关推送通知和 WNS 概念、要求和操作的概念性介绍，请参阅 Windows 推送通知服务 (WNS) 概述。
请求和接收访问令牌
本部分介绍使用 WNS 进行身份验证时涉及的请求和响应参数。
访问令牌请求
向 WNS 发送 HTTP 请求，以便对云服务进行身份验证，并检索返回的访问令牌。 使用安全套接字层 (SSL) 向 https://login.live.com/accesstoken.srf 发出请求。
访问令牌请求参数
云服务使用“application/x-www-form-urlencoded”格式在 HTTP 请求正文中提交这些必需的参数。 必须确保所有参数经过 URL 编码。
| 参数 | 必需 | 说明 |
|---|---|---|
| grant_type | TRUE | 必须设置为 client_credentials。 |
| client_id | TRUE | 将应用注册到 Microsoft Store 时为云服务分配的包安全标识符 (SID)。 |
| client_secret | TRUE | 将应用注册到 Microsoft Store 时为云服务分配的机密密钥。 |
| scope | TRUE | 必须设置为 notify.windows.com |
访问令牌响应
WNS 对云服务进行身份验证，如果成功，则以“200 正常”做出响应并包含访问令牌。 否则，WNS 以 OAuth 2.0 协议草案中所述的相应 HTTP 错误代码做出响应。
访问令牌响应参数
如果云服务成功通过身份验证，则会在 HTTP 响应中返回访问令牌。 此访问令牌在过期之前可在通知请求中使用。 HTTP 响应使用“application/json”媒体类型。
| 参数 | 必需 | 说明 |
|---|---|---|
| access_token | TRUE | 云服务在发送通知时使用的访问令牌。 |
| token_type | FALSE | 始终作为 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",
"expires_in": 86400
}
发送通知请求并接收响应
本部分介绍向 WNS 发送的 HTTP 通知传送请求中涉及的标头以及回复中涉及的标头。
- 发送通知请求
- 发送通知响应
- 不支持的 HTTP 功能
发送通知请求
发送通知请求时，调用方应用将通过 SSL 向通道统一资源标识符 (URI) 发出 HTTP 请求。 “Content-Length”是必须在请求中指定的标准 HTTP 标头。 所有其他标准标头是可选的，或者不受支持。
此外，此处列出的自定义请求标头可在通知请求中使用。 有些标头是必需的，而有些标头是可选的。
请求参数
| 标头名称 | 必须 | 说明 |
|---|---|---|
| 授权 | TRUE | 用于对通知请求进行身份验证的标准 HTTP 授权标头。 云服务在此标头中提供其访问令牌。 |
| Content-Type | TRUE | 标准 HTTP 授权标头。 对于 toast、磁贴和锁屏提醒通知，此标头必须设置为 text/xml。 对于原始通知，此标头必须设置为 application/octet-stream。 |
| Content-Length | TRUE | 用于表示请求有效负载大小的标准 HTTP 授权标头。 |
| X-WNS-Type | TRUE | 定义有效负载中的通知类型：磁贴、toast、锁屏提醒或原始。 |
| X-WNS-Cache-Policy | FALSE | 启用或禁用通知缓存。 此标头仅适用于磁贴、锁屏提醒和原始通知。 |
| X-WNS-RequestForStatus | FALSE | 请求通知响应中的设备状态和 WNS 连接状态。 |
| X-WNS-Tag | FALSE | 用于提供带有标识标签的通知的字符串，可供支持通知队列的磁贴使用。 此标头仅适用于磁贴通知。 |
| X-WNS-TTL | FALSE | 用于指定生存时间 (TTL) 的整数值，以秒表示。 |
| MS-CV | FALSE | 用于请求的关联向量值。 |
重要事项
- 无论请求中是否包含其他标准标头，在传送到客户端的通知中只会包含标准 HTTP 标头 Content-Length 和 Content-Type。
- 如果功能不受支持，则所有其他标准 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
| 值 | 说明 |
|---|---|
| wns/badge | 在磁贴上创建锁屏提醒叠加的通知。 通知请求中包含的 Content-Type 标头必须设置为 text/xml。 |
| wns/tile | 更新磁贴内容的通知。 通知请求中包含的 Content-Type 标头必须设置为 text/xml。 |
| wns/toast | 在客户端上引发 toast 的通知。 通知请求中包含的 Content-Type 标头必须设置为 text/xml。 |
| wns/raw | 可包含自定义有效负载并直接传送到应用的通知。 通知请求中包含的 Content-Type 标头必须设置为 application/octet-stream。 |
X-WNS-Cache-Policy
当通知目标设备脱机时，WNS 将为每个通道 URI 缓存一个锁屏提醒通知、一个磁贴通知和一个 toast 通知。 默认不会缓存原始通知，但如果启用了原始通知缓存，则会缓存一个原始通知。 项不会无限期保存在缓存中，而是在一段合理的时间后被删除。 否则，会在设备下次联机时传送缓存的内容。
X-WNS-Cache-Policy: cache | no-cache
| 值 | 说明 |
|---|---|
| cache | 默认。 如果用户已脱机，则会缓存通知。 这是磁贴通知和锁屏提醒通知的默认设置。 |
| no-cache | 如果用户已脱机，则不会缓存通知。 这是原始通知的默认设置。 |
X-WNS-RequestForStatus
指定响应是否应包括设备状态和 WNS 连接状态。 此标头是可选的。
X-WNS-RequestForStatus: true | false
| 值 | 说明 |
|---|---|
| 是 | 在响应中返回设备状态和通知状态。 |
| false | 默认。 不返回设备状态和通知状态。 |
X-WNS-Tag
为通知分配标记标签。 当应用已选择启用通知循环时，该标记将在通知队列中磁贴的替换策略中使用。 如果队列中已存在具有此标记的通知，该通知将由具有相同标记的新通知取代。
注意
此标头是可选的，仅在发送磁贴通知时使用。
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
| 值 | 说明 |
|---|---|
| 是 | 将 toast 通知直接发送到操作中心；不引发 toast UI。 |
| false | 默认。 引发 toast UI，并将通知添加到操作中心。 |
X-WNS-Group
注意
仅当具有同一标记的多个 Toast 通知已标为属于不同的组时，Windows Phone 应用商店应用的操作中心才能显示这些通知。 以某个食谱应用为例。 每本食谱由一个标记标识。 包含有关该食谱的评论的 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 | FALSE | 报告问题时应记录的调试信息，用于帮助排查问题。 |
| X-WNS-DeviceConnectionStatus | FALSE | 设备状态，仅当通过 X-WNS-RequestForStatus 标头在通知请求中请求时才返回此信息。 |
| X-WNS-Error-Description | FALSE | 应记录的用户可读错误字符串，用于帮助调试。 |
| X-WNS-Msg-ID | FALSE | 通知的唯一标识符，用于调试目的。 报告问题时，应记录此信息以帮助进行故障排除。 |
| X-WNS-Status | FALSE | 指示 WNS 是否成功接收并处理了通知。 报告问题时，应记录此信息以帮助进行故障排除。 |
| MS-CV | FALSE | 报告问题时应记录的调试信息，用于帮助排查问题。 |
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: connected | disconnected | tempdisconnected
| 值 | 说明 |
|---|---|
| 已连接 | 设备已联机且已连接到 WNS。 |
| 已断开连接 | 设备已脱机且未连接到 WNS。 |
| tempconnected（已弃用） | 设备暂时与 WNS 断开连接，例如，在断开 3G 连接或断开笔记本电脑上的无线开关时。 通知客户端平台将此状态视为暂时性中断而不是有意断开连接。 |
X-WNS-Error-Description
此标头提供应记录的、用于帮助调试的用户可读错误字符串。
X-WNS-Error-Description: <string value>
| 值 | 说明 |
|---|---|
| 字符串值 | 一个字母数字字符串。 |
X-WNS-Msg-ID
此标头用于为调用方提供通知标识符。 我们建议记录此标头，以帮助调试问题。 向 WNS 报告问题时，需要提供此标头以及 X-WNS-Debug-Trace 和 MS-CV。
X-WNS-Msg-ID: <string value>
| 值 | 说明 |
|---|---|
| 字符串值 | 一个字母数字字符串，其长度不超过 16 个字符。 |
X-WNS-Status
此标头描述 WNS 如何处理通知请求。 如果不想要将响应代码解释为成功或失败，可以使用此标头。
X-WNS-Status: received | dropped | channelthrottled
| 值 | 说明 |
|---|---|
| received | WNS 已接收并处理通知。 注意：�这并不保证设备收到了通知。 |
| 已删除 | 由于出错或者客户端已显式拒绝这些通知，因此显式删除了通知。 如果设备已脱机，则也会删除 Toast 通知。 |
| channelthrottled | 由于应用服务器超出了此特定通道的速率限制，因此删除了通知。 |
MS-CV
此标头提供与主要用于调试的请求相关的关联向量。 如果已提供 CV 作为请求的一部分，则 WNS 将使用该值，否则 WNS 将生成一个 CV 并在响应中返回该 CV。 向 WNS 报告问题时，需要提供此标头以及 X-WNS-Debug-Trace 和 X-WNS-Msg-ID 标头。
重要
如果你提供自己的 CV，请为每个推送通知请求生成一个新的 CV。
MS-CV: <string value>
| 值 | 说明 |
|---|---|
| 字符串值 | 遵循关联向量标准 |
响应代码
每个 HTTP 消息包含下列响应代码之一。 WNS 建议开发人员记录该响应代码，以便在调试中使用。 开发人员在向 WNS 报告问题时，需要提供响应代码和标头信息。
| HTTP 响应代码 | 说明 | 建议的操作 |
|---|---|---|
| 200 OK | WNS 已接受通知。 | 不需要。 |
| 400 错误请求 | 错误地指定了一个或多个标头，或者指定的标头与另一个标头冲突。 | 记录请求的详细信息。 检查请求并与此文档进行比较。 |
| 401 未授权 | 云服务未提供有效的身份验证票证。 OAuth 票证可能无效。 | 通过使用访问令牌请求对云服务进行身份验证来请求有效的访问令牌。 |
| 403 禁止访问 | 即使已通过身份验证，云服务也无权向此 URI 发送通知。 | 请求中提供的访问令牌与请求通道 URI 的应用的凭据不匹配。 确保应用清单中的包名称与仪表板中提供给应用的云服务凭据相匹配。 |
| 404 未找到 | 通道 URI 无效或未被 WNS 识别。 | 记录请求的详细信息。 不要向此通道发送更多的通知；发送到此地址的通知将会失败。 |
| 405 不允许的方法 | 无效的方法（GET、CREATE）；只允许 POST（Windows 或 Windows Phone）或 DELETE（仅适用于 Windows Phone）。 | 记录请求的详细信息。 请改用 HTTP POST。 |
| 406 不可接受 | 云服务超出了其限制。 | 请在响应中的 Retry-After 标头值后面发送请求 |
| 410 不存在 | 通道已过期。 | 记录请求的详细信息。 不要向此通道发送更多的通知。 让应用请求新的通道 URI。 |
| 410 域被阻止 | 发送域已被 WNS 阻止。 | 不要向此通道发送更多的通知。 发送域因滥用推送通知而被 WNS 阻止。 |
| 413 请求实体太大 | 通知有效负载超出了 5000 字节大小限制。 | 记录请求的详细信息。 检查有效负载，确保它在大小限制范围内。 |
| 500 内部服务器错误 | 某个内部故障导致通知传送失败。 | 记录请求的详细信息。 通过开发人员论坛报告此问题。 |
| 503 服务不可用 | 服务器当前不可用。 | 记录请求的详细信息。 通过开发人员论坛报告此问题。 如果已观察到 Retry-After 标头，请在响应中的 Retry-After 标头值后面发送请求。 |
不支持的 HTTP 功能
WNS Web 界面支持 HTTP 1.1，但不支持以下功能：
- 分块
- 管道（POST 不是幂等的）
- 尽管支持 Expect-100，但开发人员应禁用它，因为它会在发送通知时造成延迟。
