推送通知服务请求和响应头(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 应用商店注册应用时已分配的云服务密钥。
作用域 必需 必须设置为:
  • Windows:“notify.windows.com”
  • Windows Phone:“notify.windows.com”或“s.notify.live.net”

 

访问令牌响应

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,因为发送通知时它会引入延迟。

相关主题

快速入门:发送推送通知

推送通知指南和清单

如何使用 Windows 推送通知服务 (WNS) 进行验证

如何请求、创建和保存通知通道

推送和定期通知示例

WNS 概述