诊断 Azure 通知中心内删除通知的问题Diagnose dropped notifications in Azure Notification Hubs

对于 Azure 通知中心,一个常见问题是如何排查客户端设备上不显示应用程序发出的通知的问题。A common question about Azure Notification Hubs is how to troubleshoot when notifications from an application don't appear on client devices. 客户想要知道删除通知的位置和原因以及如何修复该问题。Customers want to know where and why notifications were dropped, and how to fix the issue. 本文标识了通知被删除或设备收不到通知的各种原因。This article identifies why notifications might get dropped or not be received by devices. 此外还介绍了如何确定根本原因。It also explains how to determine the root cause.

首先务必了解通知中心如何将通知推送到设备。It's critical to first understand how Notification Hubs pushes notifications to a device.


在典型的发送通知流中,消息从 应用程序后端 发送到通知中心。In a typical send notification flow, the message is sent from the application back end to Notification Hubs. 通知中心处理所有注册。Notification Hubs processes all the registrations. 它会考虑配置的标记和标记表达式,以确定目标。It takes into account the configured tags and tag expressions to determine targets. 目标是指需要接收推送通知的注册。Targets are the registrations that need to receive the push notification. 这些注册可能跨越所有受支持的平台:Android、百度(中国的 Android 设备)、Fire OS (Amazon) iOS、Windows 和 Windows Phone。These registrations can span any of our supported platforms: Android, Baidu (Android devices in China), Fire OS (Amazon) iOS, Windows, and Windows Phone.

确定目标之后,通知中心将通知推送到设备平台的 推送通知服务With the targets established, Notification Hubs pushes notifications to the push notification service for the device platform. 示例包括适用于 iOS 和 macOS 的 Apple Push Notification 服务 (APNs)。Examples include the Apple Push Notification service (APNs) for iOS and macOS. 通知中心推送跨多批注册拆分的通知。Notification Hubs pushes notifications split across multiple batches of registrations. 通知中心基于你在 Azure 门户的“配置通知中心” 下设置的凭据,向各自的推送通知服务验证身份。It authenticates with the respective push notification service, based on the credentials you set in the Azure portal, under Configure Notification Hub. 然后,推送通知服务将通知转发到各自的 客户端设备The push notification service then forwards the notifications to the respective client devices.

通知传递的最后一步在平台推送通知服务与设备之间进行。The final leg of notification delivery is between the platform's push notification service and the device. 通知传送可能会在推送通知过程的四个阶段(客户端、应用程序后端、通知中心和平台推送通知服务)中的任何一个阶段失败。Notification delivery can fail at any of the four stages in the push notification process (client, application back end, Notification Hubs, and the platform's push notification service). 有关通知中心体系结构的详细信息,请参阅通知中心概述For more information about the Notification Hubs architecture, see Notification Hubs overview.

在初始测试/暂存阶段,可能出现无法传递通知的情况。A failure to deliver notifications might occur during the initial test/staging phase. 于此阶段删除的通知可能表示存在配置问题。Dropped notifications at this stage might indicate a configuration issue. 如果在生产阶段出现无法传递通知的情况,则可能删除部分或全部通知。If a failure to deliver notifications occurs in production, some or all of the notifications might be dropped. 这种情况表示存在更深层次的应用程序或消息模式问题。A deeper application or messaging pattern issue is indicated in this case.

下一部分将着眼于各种可能删除通知的场景,从常见类型到更加稀有的类型一应俱全。The next section looks at scenarios in which notifications might be dropped, ranging from common to rare.

通知中心配置错误Notification Hubs misconfiguration

若要将通知发送到各自的推送通知服务,通知中心必须在应用程序环境中对自身进行身份验证。To send notifications to the respective push notification service, Notification Hubs must authenticate itself in the context of your application. 必须通过目标平台的通知服务(Microsoft、Apple 等)创建开发人员帐户。You must create a developer account with the target platform's notification service (Microsoft, Apple, etc.). 然后,必须将应用程序注册到 OS,你在该 OS 中获取与目标 PNS 配合使用的令牌或密钥。Then, you must register your application with the OS where you get a token or key that you use to work with the target PNS.

你必须将平台凭据添加到 Azure 门户中。You must add platform credentials to the Azure portal. 如果设备未收到任何通知,第一步是确保在通知中心配置正确的凭据。If no notifications are reaching the device, the first step is to ensure the correct credentials are configured in Notification Hubs. 凭据必须与在平台特定开发人员帐户下创建的应用程序相匹配。The credentials must match the application that's created under a platform-specific developer account.

有关如何完成此过程的分步说明,请参阅 Azure 通知中心入门For step-by-step instructions to complete this process, see Get started with Azure Notification Hubs.

下面是一些需要检查的常见错误配置:Here are some common misconfigurations to check for:

通知中心名称位置Notification hub name location

确保以下各个位置中的通知中心名称(不含错字)均相同:Ensure that your notification hub name (without typos) is the same in each of these locations:

  • 从客户端注册的位置Where you register from the client
  • 从后端发送通知的位置Where you send notifications from the back end
  • 配置推送通知服务凭据的位置Where you configured the push notification service credentials

确保在客户端和应用程序后端上使用正确的共享访问签名配置字符串。Ensure you use the correct shared access signature configuration strings on the client and the application back end. 一般而言,必须在客户端上使用 DefaultListenSharedAccessSignature,在应用程序后端上使用 DefaultFullSharedAccessSignatureGenerally, you must use DefaultListenSharedAccessSignature on the client and DefaultFullSharedAccessSignature on the application back end. 这会授予向通知中心发送通知的权限。This grants permissions to send notifications to Notification Hubs.

APN 配置APN configuration

必须维护两个不同的中心:一个用于生产目的,另一个用于测试。You must maintain two different hubs: one for production and another for testing. 必须将在沙盒环境中使用的证书上传到一个中心,将要在生产环境中使用的证书上传到另一个中心。You must upload the certificate you use in a sandbox environment to a separate hub than the certificate/hub you'll use in production. 请勿尝试将不同类型的证书上传到相同的中心。Don't try to upload different types of certificates to the same hub. 这会导致通知失败。It will cause notification failures.

如果无意中将不同类型的证书上传到相同的中心,应删除该中心并重新上传到新的中心。If you inadvertently upload different types of certificates to the same hub, you should delete the hub and start fresh with a new hub. 如果出于某种原因无法删除该中心,最起码必须从该中心删除所有现有注册。If for some reason you can't delete the hub, you must at least delete all the existing registrations from the hub.

应用程序问题Application issues

标记和标记表达式Tags and tag expressions

如果使用标记或标记表达式来细分受众,在发送通知时可能找不到目标。If you use tags or tag expressions to segment your audience, it's possible that when you send the notification, no target is found. 此错误根据 send 调用中指定的标记或标记表达式而定。This error is based on the specified tags or tag expressions in your send call.

发送通知时,请查看注册,确保有匹配的标记。Review your registrations to ensure the tags match when you send a notification. 然后,确保仅从含有这些注册的客户端收到通知。Then, verify the notification receipt from only the clients that have those registrations.

例如,假设使用“政治”标记向通知中心注册了所有设备。For example, suppose all your registrations with Notification Hubs use the tag "Politics." 如果使用“体育”标记发送通知,则通知将不会发送到任何设备。If you then send a notification with the tag "Sports," the notification won't be sent to any device. 复杂的用例可能涉及到标记表达式,其中已使用“标记 A”或“标记 B”进行注册,但目标是“标记 A 和 标记 B”。 A complex case might involve tag expressions where you registered by using "Tag A" or "Tag B," but you targeted "Tag A && Tag B." 本文稍后的自我诊断提示部分将介绍如何查看注册及其标记。The self-diagnosis tips section later in the article shows you how to review your registrations and their tags.

模板问题Template issues

如果使用模板,请确保遵循模板中所述的准则。If you use templates, ensure that you follow the guidelines described in Templates.

注册无效Invalid registrations

如果通知中心配置正确,所有标记或标记表达式的用法也正确,则会找到有效的目标。If the notification hub was configured correctly and tags or tag expressions were used correctly, valid targets are found. 应将通知发送到这些目标。Notifications should be sent to these targets. 接着,通知中心会并行启动几个处理批次。Notification Hubs then fires off several processing batches in parallel. 每个批次将消息发送到一组注册。Each batch sends messages to a set of registrations.


由于通知中心并行处理批次,因此不保证通知的传送顺序。Because Notification Hubs processes batches in parallel, the order in which the notifications are delivered is not guaranteed.

通知中心已针对“最多一次”消息传递模型进行优化。Notification Hubs is optimized for an "at-most-once" message delivery model. 我们尝试执行重复数据消除,从而不向设备传递一次以上的通知。We attempt deduplication, so that no notifications are delivered more than once to a device. 在将消息发送到推送通知服务之前,会检查注册以确保仅为每个设备标识符发送一条消息。Registrations are checked to ensure that only one message is sent per device identifier before it's sent to the push notification service.

每个批次将发送到推送通知服务,后者接受并验证注册。Each batch is sent to the push notification service, which in turn accepts and validates the registrations. 在此过程中,推送通知服务可能会在某个批次中检测到一个或多个注册的错误。During this process, it's possible that the push notification service will detect an error with one or more registrations in a batch. 然后,推送通知服务会向通知中心返回错误,而推送过程将会停止。The push notification service then returns an error to Notification Hubs, and the process stops. 推送通知服务会完全删除该批次。The push notification service drops that batch completely. 对于使用 TCP 流协议的 APNs 也是如此。This is especially true with APNs, which uses a TCP stream protocol.

在这种情况下,出错的注册会从数据库中删除。In this case, the faulting registration is removed from the database. 然后,我们针对该批次中的其他设备重试通知传递。Then, we retry notification delivery for the rest of the devices in that batch.

若要获取有关针对注册的失败传递尝试的更多错误信息,可以使用通知中心 REST API 按消息遥测:获取通知消息遥测数据PNS 反馈To get more error information about the failed delivery attempt against a registration, you can use the Notification Hubs REST APIs Per Message Telemetry: Get Notification message telemetry and PNS feedback. 有关示例代码,请参阅发送 REST 示例For sample code, see the Send REST example.

推送通知服务问题Push notification service issues

推送通知服务收到通知后,会将通知传送到设备。After the push notification service receives the notification, it delivers the notification to the device. 此时,通知中心无法控制向设备传送通知的操作。At this point, Notification Hubs has no control over the delivery of the notification to the device.

由于平台通知服务非常强大,通知往往在几秒内即可抵达设备。Because platform notification services are robust, notifications tend to reach devices in a few seconds. 如果推送通知服务进行限制,通知中心会应用指数回退策略。If the push notification service is throttling, Notification Hubs applies an exponential back-off strategy. 如果推送通知服务在 30 分钟之内都无法访问,会实施一个策略,让消息过期并永久删除它们。If the push notification service remains unreachable for 30 minutes, there's a policy in place to expire and drop the messages permanently.

如果推送通知服务尝试传递通知,但设备处于脱机状态,则推送通知服务会存储通知。If a push notification service attempts to deliver a notification but the device is offline, the notification is stored by the push notification service. 通知只会存储有限的一段时间。It's stored for only a limited period of time. 等设备可用时再将通知传递到设备。The notification is delivered to the device when the device becomes available.

每个应用仅存储一个最新通知。Each app stores only one recent notification. 如果在设备处于脱机状态时发送了多个通知,则每个新通知将导致上一个通知被放弃。If multiple notifications are sent while a device is offline, each new notification causes the last one to be discarded. 只保留最新通知的行为在 APNs 中称为“合并” 。Keeping only the newest notification is called coalescing in APNs. 如果设备长时间处于脱机状态,则放弃为它存储的通知。When the device remains offline for a long time, notifications that were stored for the device are discarded. 有关详细信息,请参阅 APNs 概述For more information, see APNs Overview.

在通知中心,可以使用泛型 SendNotification API 通过 HTTP 标头来传递合并密钥。With Notification Hubs, you can pass a coalescing key via an HTTP header by using the generic SendNotification API. 例如,对于 .NET SDK,你会使用 SendNotificationAsyncFor example, for the .NET SDK, you'd use SendNotificationAsync. SendNotification API 还会将按原样传递的 HTTP 标头传递到各自的推送通知服务。The SendNotification API also takes HTTP headers that are passed as is to the respective push notification service.

自我诊断提示Self-diagnosis tips

下面介绍了诊断通知中心已删除通知的根本原因的各种途径。Here are paths to diagnose the root cause of dropped notifications in Notification Hubs.

验证凭据Verify credentials

推送通知服务开发人员门户Push notification service developer portal

在各自的推送通知服务开发人员门户(APNs、Windows 通知服务等)中验证凭据。Verify credentials in the respective push notification service developer portal (APNs, Windows Notification Service, and so on). 有关详细信息,请参阅教程:使用 Azure 通知中心向通用 Windows 平台应用发送通知创建的解决方案。For more information, see Tutorial: Send notifications to Universal Windows Platform apps by using Azure Notification Hubs.

Azure 门户Azure portal

若要查看凭据并将凭据与从推送通知服务开发人员门户获取的凭据进行匹配,请在 Azure 门户中转到“访问策略” 选项卡。To review and match the credentials with those you obtained from the push notification service developer portal, go to the Access Policies tab in the Azure portal.

Azure 门户访问策略

验证注册Verify registrations

Visual StudioVisual Studio

在 Visual Studio 中,可以通过服务器资源管理器连接到 Azure,以查看和管理包括通知中心在内的多个 Azure 服务。In Visual Studio, you can connect to Azure through Server Explorer to view and manage multiple Azure services, including Notification Hubs. 此快捷方式主要用于开发/测试环境。This shortcut is primarily useful for your development/test environment.

Visual Studio 服务器资源管理器


可以查看和管理中心内的所有注册。You can view and manage all the registrations in your hub. 这些注册可按平台、本机或模板注册、标记、推送通知服务标识符、注册 ID 及过期日期分类。The registrations can be categorized by platform, native or template registration, tag, push notification service identifier, registration ID, and expiration date. 还可以在此页面中编辑注册。You can also edit a registration on this page. 它对于编辑标记特别有用。It's especially useful for editing tags.

在“服务器资源管理器”中右键单击你的通知中心,然后选择“诊断”。 Right-click your notification hub in Server Explorer, and select Diagnose.

Visual Studio 服务器资源管理器:“诊断”菜单

会看到以下页面:You see the following page:

Visual Studio:“诊断”页

切换到“设备注册”页: Switch to the Device Registrations page:

Visual Studio:设备注册

若要发送测试通知消息,可以使用“测试性发送”页: You can use Test Send page to send a test notification message:

Visual Studio:测试发送


用于编辑注册的 Visual Studio 功能只能在开发/测试有限的注册时使用。Use Visual Studio to edit registrations only during development/test, and with a limited number of registrations. 如果需要批量编辑注册,请考虑使用以下教程中所述的导出和导入注册功能:如何:批量导出和修改注册If you need to edit your registrations in bulk, consider using the export and import registration functionality described in How To: Export and Modify Registrations in Bulk.

服务总线资源管理器Service Bus Explorer

许多客户使用服务总线资源管理器来查看和管理自己的通知中心。Many customers use Service Bus Explorer to view and manage their notification hubs. 服务总线资源管理器是一个开源项目。Service Bus Explorer is an open-source project.

验证消息通知Verify message notifications

Azure 门户Azure portal

若要向客户端发送测试通知,而不启动和运行服务后端,请在“支持 + 故障排除” 下选择“测试发送” 。To send a test notification to your clients without having a service back end up and running, under SUPPORT + TROUBLESHOOTING, select Test Send.

Azure 中的测试发送功能

Visual StudioVisual Studio

也可以从 Visual Studio 发送测试通知。You can also send test notifications from Visual Studio.

Visual Studio 中的测试发送功能

有关将通知中心与 Visual Studio 服务器资源管理器搭配使用的详细信息,请参阅以下文章:For more information about using Notification Hubs with Visual Studio Server Explorer, see these articles:

调试失败的通知和查看通知结果Debug failed notifications and review notification outcome

EnableTestSend 属性EnableTestSend property

通过通知中心发送通知时,通知最初将会排队。When you send a notification via Notification Hubs, the notification is initially queued. 通知中心确定正确的目标后,便将通知发送到推送通知服务。Notification Hubs determines the correct targets, and then sends the notification to the push notification service. 如果使用 REST API 或任意客户端 SDK,send 调用的返回只表示消息已在通知中心排队。If you're using the REST API or any of the client SDKs, the return of your send call means only that the message is queued with Notification Hubs. 至于通知中心最终将消息发送到推送通知服务时发生了什么情况,此调用不提供任何深入信息。It doesn't provide insight into what happened when Notification Hubs eventually sent the notification to the push notification service.

如果通知未抵达客户端设备,原因可能是当通知中心尝试将消息传送到推送通知服务时发生了错误。If your notification doesn't arrive at the client device, an error might have occurred when Notification Hubs tried to deliver it to the push notification service. 例如,有效负载大小可能超出了推送通知服务允许的上限,或者在通知中心配置的凭据可能无效。For example, the payload size might exceed the maximum allowed by the push notification service, or the credentials configured in Notification Hubs might be invalid.

若要深入了解推送通知服务错误,可以使用 EnableTestSend 属性。To get insight into push notification service errors, you can use the EnableTestSend property. 从门户或 Visual Studio 客户端发送测试消息时,系统会自动启用此属性。This property is automatically enabled when you send test messages from the portal or Visual Studio client. 可以使用此属性以及通过 API 查看详细的调试信息。You can use this property to see detailed debugging information and also via APIs. 目前可在 .NET SDK 中使用此属性。Currently, you can use it in the .NET SDK. 最终,它将添加到所有客户端 SDK 中。It will be added to all client SDKs eventually.

若要结合使用 EnableTestSend 属性和 REST 调用,可在发送调用的末尾追加名为 test 的查询字符串参数 。To use the EnableTestSend property with the REST call, append a query string parameter called test to the end of your send call. 例如:For example:


.NET SDK 示例.NET SDK example

下面是使用 .NET SDK 发送本机弹出 (toast) 通知的示例:Here's an example of using the .NET SDK to send a native pop-up (toast) notification:

NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(connString, hubName);
var result = await hub.SendWindowsNativeNotificationAsync(toast);

在执行结束时,result.State 只表示 EnqueuedAt the end of the execution, result.State simply states Enqueued. 结果未深入分析推送通知发生了什么。The results don't provide any insight into what happened to your push notification.

接下来,可以使用 EnableTestSend 布尔属性。Next, you can use the EnableTestSend Boolean property. 初始化 NotificationHubClient 时,可使用 EnableTestSend 属性获取有关发送通知时出现的推送通知服务错误的详细状态。Use the EnableTestSend property while you initialize NotificationHubClient to get a detailed status about push notification service errors that occur when the notification is sent. send 调用需要更多时间才能返回,因为它首先需要通知中心将通知传送到推送通知服务。The send call takes additional time to return because it first needs Notification Hubs to deliver the notification to the push notification service.

    bool enableTestSend = true;
    NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(connString, hubName, enableTestSend);

    var outcome = await hub.SendWindowsNativeNotificationAsync(toast);

    foreach (RegistrationResult result in outcome.Results)
        Console.WriteLine(result.ApplicationPlatform + "\n" + result.RegistrationId + "\n" + result.Outcome);

示例输出Sample output

The Token obtained from the Token Provider is wrong

此消息表示在通知中心内配置的凭据无效,或者中心内的注册有问题。This message indicates either that the credentials configured in Notification Hubs are invalid or that there's an issue with the registrations in the hub. 请删除此注册,让客户端重新创建注册后再发送消息。Delete this registration and let the client re-create the registration before sending the message.


使用 EnableTestSend 属性受到严重限制。Use of the EnableTestSend property is heavily throttled. 此选项只能在开发/测试环境中与一组有限的注册结合使用。Use this option only in a development/test environment and with a limited set of registrations. 调试通知只会发送到 10 个设备。Debug notifications are sent to only 10 devices. 此外,限制为每分钟最多处理 10 个调试发送操作。There's also a limit on processing debug sends, at 10 per minute.

查看遥测Review telemetry

Azure 门户Azure portal

在该门户中,可以快速了解通知中心的所有活动。In the portal, you can get a quick overview of all the activity in your notification hub.

  1. 在“概述” 选项卡上,可以查看每个平台的注册、通知和错误的汇总视图。On the Overview tab, you can see an aggregated view of registrations, notifications, and errors by platform.


  2. 在“监视器” 选项卡上,可以添加许多其他平台特定指标,以便进行深入了解。On the Monitor tab, you can add many other platform-specific metrics for a deeper look. 可以专门查看当通知中心尝试将通知发送到推送通知服务时返回的错误。You can look specifically at errors that are returned when Notification Hubs tries to send the notification to the push notification service.

    Azure 门户活动日志

  3. 首先查看“传入消息” 、“注册操作” 和“成功通知” 。Begin by reviewing Incoming Messages, Registration Operations, and Successful Notifications. 然后转到每个平台选项卡查看特定于推送通知服务的错误。Then, go to the per-platform tab to review errors that are specific to the push notification service.

  4. 如果通知中心的身份验证设置不正确,则出现“PNS 身份验证错误” 消息。If the authentication settings for your notification hub are incorrect, the message PNS Authentication Error appears. 它表示要检查推送通知服务凭据。It's a good indication to check the push notification service credentials.

以编程方式访问Programmatic access

有关编程访问的详细信息,请参阅以编程方式访问For more information about programmatic access, see Programmatic access.


与遥测相关的多项功能(例如,导出和导入注册、通过 API 进行遥测访问)只能在“标准”服务层级使用。Several telemetry-related features, like exporting and importing registrations and telemetry access via APIs, are available only on the Standard service tier. 如果尝试从“免费”或“基本”服务层级使用这些功能,则在使用 SDK 时会收到异常消息。If you attempt to use these features from the Free or Basic service tier, you'll get an exception message if you use the SDK. 如果直接从 REST API 使用这些功能,将会收到 HTTP 403(已禁止)错误。You'll get an HTTP 403 (Forbidden) error if you use the features directly from the REST APIs.

若要使用与遥测相关的功能,首先确保在 Azure 门户中使用“标准”服务层级。To use telemetry-related features, first ensure in the Azure portal that you're using the Standard service tier.