导出 (0) 打印
全部展开
信息
您所需的主题如下所示。但此主题未包含在此库中。
此主题尚未评级 - 评价此主题

推送通知服务请求和响应头

此主题介绍了服务到服务的 Web API 以及发送推送通知所需的协议。

有关推送通知和 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 应用商店注册应用时已分配的云服务密钥。
作用域必需必须设置为“notify.windows.com”。

 

访问令牌响应

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 以传递通知时所涉及的头以及回复时所涉及的头。

发送通知请求

调用应用发送通知请求时,会通过 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) 的整数值(用秒数表示)。

 

重要说明

  • 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 标签。当应用已选择通知循环时,通知队列中的磁贴的替换策略中会使用标记。如果该队列中已存在带有此标记的通知,则带有相同标记的新通知会取代其位置。

注意  此头仅在发送磁贴通知时使用。

X-WNS-Tag: <string value>
描述
字符串值不超过 16 个字符的字母数字字符串。

 

X-WNS-TTL

此可选头可用于为通知指定 TTL(过期时间)。通常情况下不需要使用此头,但如果要确保通知在特定时间之后不显示,可以使用此头。TTL 以秒为单位进行指定,且与 WNS 接收请求的时间相关。如果指定了 TTL,则此后设备将不会显示通知。注意,如果 TTL 太短,则这样可能会导致根本不会显示通知。通常,过期时间的量度单位至少为分钟。

如果未指定此可选值,则通知将不会过期,并且会按照正常通知更换方案进行替换。

此头不会应用于 Toast 通知。

X-WNS-TTL: <integer value>
描述
整数值WNS 接收请求后的通知生存期跨度(以秒为单位)。

 

发送通知响应

当 WNS 处理通知请求后,它会发送 HTTP 响应消息。此部分介绍了可在该响应中找到的参数和头。

响应参数

头名称必需/可选描述
X-WNS-Debug-Trace可选报告问题时应记录用于帮助解决问题的调试信息。
X-WNS-DeviceConnectionStatus可选设备状态,仅当通过 X-WNS-RequestForStatus 头在通知请求中请求时返回。
X-WNS-Error-Description可选应记录用于帮助调试的人工可读错误。
X-WNS-Msg-ID可选通知的唯一标识符,用于调试目的。报告问题时,应记录此信息以有助于故障诊断。
X-WNS-NotificationStatus可选指示 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-NotificationStatus

此头介绍了 WNS 处理通知请求的方式。可以使用此头,但不是用于将响应代码解释为成功还是失败。

X-WNS-NotificationStatus: received | dropped | channelthrottled
描述
已接收WNS 已接收并处理通知。

注意  这并不能保证设备会收到通知。

已丢弃通知已被显式丢弃,原因是出现错误,或客户端已显式拒绝这些通知。如果设备处于脱机状态,则还会丢弃 Toast 通知。
channelthrottled通知已被丢弃,原因是应用服务器已超出此特定信道的速率限制。

 

响应代码

每个 HTTP 消息都包含这些响应代码中的一个响应代码。WNS 建议开发者记录响应代码以便用于调试。当开发者向 WNS 报告问题时,要求他们提供响应代码和头信息。

HTTP 响应代码描述建议的操作
200 OKWNS 已接收通知。不需要任何信息。
400 错误的请求一个或多个头指定错误或与其他头发生冲突。记录请求的详细信息。检查你的请求并与此文档进行比较。
401 未授权云服务未提供有效的验证票据。OAuth 票据可能无效。请求有效的访问令牌,方法是对使用访问令牌请求的云服务进行验证。
403 已禁止未授权云服务将通知发送至此 URI,即便这些通知经过验证。请求中提供的访问令牌与请求信道 URI 的应用的凭据不匹配。确保应用清单中的包名称与提供给仪表板中应用的云服务凭据匹配。
404 未找到信道 URI 无效或 WNS 无法识别该 URI。记录请求的详细信息。不将以后的通知发送至此信道;发送至此地址的通知将失败。
405 方法不允许方法无效(GET、DELETE、CREATE);仅允许使用 POST。记录请求的详细信息。切换到使用 HTTP POST。
406 无法接受云服务已超出其中止值。记录请求的详细信息。降低发送通知的速率。
410 不存在信道已过期。记录请求的详细信息。请勿将以后的通知发送至此信道。让应用请求新的通道 URI
413 请求实体太大通知负载超出 5000 字节大小限制。记录请求的详细信息。检查负载以确保该负载位于大小限制值之内。
500 内部服务器错误内部故障已导致通知传递失败。记录请求的详细信息。通过开发人员论坛报告此问题。
503 服务不可用服务器当前无法使用。记录请求的详细信息。通过开发人员论坛报告此问题。

 

不受支持的 HTTP 功能

WNS Web 接口支持 HTTP 1.1,但不支持以下功能:

  • 区块
  • 流水线处理(POST 不是幂等)
  • 尽管支持,但开发人员还是应该禁用 Expect-100,因为发送通知时它会引入延迟。

相关主题

快速入门:发送推送通知
推送通知指南和清单
如何使用 Windows 推送通知服务 (WNS) 进行验证
如何请求、创建和保存通知通道
推送和定期通知示例
推送通知概述

 

 

本文是否对您有所帮助?
(1500 个剩余字符)
感谢您的反馈
显示:
© 2014 Microsoft. 版权所有。