你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
获取通知消息遥测
此 API 提供有关传出推送通知的已完成状态的其他遥测数据。 它旨在帮助监视从中心发送的推送通知。 可以从用于发送通知的 REST API 的响应中包含的 HTTP 位置标头中检索此 API 使用的通知 ID。
此按消息遥测功能也适用于 计划通知。
此 API 仅适用于 标准层通知中心。
请求
| 方法 | 请求 URI | HTTP 版本 |
|---|---|---|
| GET | https://{namespace}.servicebus.windows.net/{NotificationHub}/messages/{notification message ID}?api-version=2016-07 |
HTTP/1.1 |
请求标头
下表介绍必需的和可选的请求标头。
| 请求标头 | 说明 |
|---|---|
| 授权 | 使用 服务总线进行共享访问签名身份验证中指定的生成的 SAS 令牌。 |
| x-ms-version | 2016-07 (2015-01 或更高版本支持) |
请求正文
无。
响应
响应包括 HTTP 状态代码和一组响应标头。 成功时返回响应正文。
响应代码
| 代码 | 说明 |
|---|---|
| 200 | 已成功检索消息遥测。 遥测数据可能是部分响应，具体取决于发送的通知消息所针对的设备数，以及消息在系统中进行处理的进度。 |
| 400 | 无法检索消息遥测，因为请求格式不正确。 |
| 401 | 授权失败。 访问密钥不正确。 |
| 403 | 请求被拒绝，因为未为 SKU 启用此功能。 升级到标准。 |
| 404 | 遥测不存在。 当通知 ID 无效时，可能会发生此错误。 |
有关状态代码的信息，请参阅 状态和错误代码。
响应头
| 响应标头 | 说明 |
|---|---|
| Content-type | application/xml; charset=utf-8 |
响应正文
响应正文是一个由以下元素组成的 NotificationDetails 文档：
| 元素 | 说明 |
|---|---|
| NotificationId | 传递给标识通知消息的请求的 ID。 |
| 位置 | 消息的 URI |
| 状态 | 指示消息进度。 State 可以是以下值之一：
|
| EnqueueTime | 指示消息被接受的时间。 |
| StartTime | 指示通知中心服务何时开始处理通知。 |
| EndTime | 指示通知中心服务何时完成对通知的工作。 |
| NotificationBody | 原始通知消息的正文。 |
| TargetPlatforms | 指示通知面向的平台。 可以包含以下值，以逗号分隔的字符串：
|
| ApnsOutcomeCounts | 对于发送到 Apple 推送通知服务的通知，存在此元素。 包含结果实例的集合。 |
| MpnsOutcomeCounts | 对于发送到 Microsoft 推送通知服务的通知，存在此元素。 包含结果实例的集合。 |
| WnsOutcomeCounts | 此元素用于发送到 Windows 通知服务的通知。 包含结果实例的集合。 |
| GcmOutcomeCounts | 此元素用于发送到 Google Cloud Messaging 的通知。 包含结果实例的集合。 |
| AdmOutcomeCounts | 此元素用于发送到 Amazon 设备消息传送的通知。 包含结果实例的集合。 |
| 业务成效 | 这些实例的集合构成每个平台通知服务的上述计数。 每个结果可以是“ 结果 ”部分中提到的命名计数之一。 |
| PnsErrorDetailsUri | 需要 Api-Version 2016-07 及更高版本用于此 API 和发送通知消息的 API。 PNS 错误详细信息仅在关联的发送操作完成后才完全可用。 获取 Blob 的 URI，其中包含所涉及的每个 PNS 返回的错误。 如果 PNS 未报告任何错误，则响应中不包含此成员。 可以使用 Azure 存储 API 读取 Blob。 有关详细信息，请参阅 通过 .NET 开始使用 Azure Blob 存储 或 Azure 存储服务 REST API 参考 可能的 PNS 错误包括：
|
结果
| 名称 | 计数说明 |
|---|---|
| AbandonedNotificationMessages | 由于超时而丢弃的推送服务的发送请求计数。 |
| BadChannel | 由于通道无效，与推送服务的通信失败。 |
| ChannelDisconnected | 推送服务已断开连接。 |
| ChannelThrottled | 推送服务因限制而拒绝访问。 |
| Dropped | 推送服务指示消息已删除。 |
| ExpiredChannel | 由于通道已过期，与推送服务的通信失败。 |
| InvalidCredentials | 用于向推送服务进行身份验证的凭据失败。 |
| InvalidNotificationSize | 推送请求太大。 |
| NoTargets | 找不到要发送到的请求计数。 |
| PnsInterfaceError | 推送服务协定通信失败。 |
| PnsServerError | 推送服务指示其端发生了错误。 |
| PnsUnavailable | 推送服务不可用。 |
| PnsUnreachable | 推送服务无响应。 |
| 已跳过 | (找到同一 PNS 句柄、不同注册 ID) 的重复注册计数。 |
| 成功 | 已成功将请求发送到某些数量的设备。 |
| 已中止 | 推送服务因限制而拒绝访问。 |
| UnknownError | 发生未知错误。 |
| WrongToken | PNS 未将 PNS 句柄识别为有效句柄。 |
下面是向 WNS 发送通知的示例遥测数据：
<NotificationDetails xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<NotificationId>{Your message id}</NotificationId>
<Location>sb://{Your namespace}.servicebus.windows.net/{your hub name}/messages/{your message id}?api-version=2015-04</Location>
<State>Completed</State>
<EnqueueTime>2015-11-02T21:19:43Z</EnqueueTime>
<StartTime>2015-11-02T21:19:43.9926996Z</StartTime>
<EndTime>2015-11-02T21:19:43.9926996Z</EndTime>
<NotificationBody><?xml version="1.0" encoding="utf-16"?><toast><visual><binding template="ToastText01"><text id="1">Hello from a .NET App!</text></binding></visual></toast></NotificationBody>
<TargetPlatforms>windows</TargetPlatforms>
<WnsOutcomeCounts>
<Outcome>
<Name>Success</Name>
<Count>3</Count>
</Outcome>
<Outcome>
<Name>WrongToken</Name>
<Count>1</Count>
</Outcome>
</WnsOutcomeCounts>
<PnsErrorDetailsUri>{Blob uri}</PnsErrorDetailsUri>
</NotificationDetails>