消息路由故障排除
本文提供关于如何监视和解决 IoT 中心消息路由的常见问题的指导。
监视消息路由
建议监视与消息路由和终结点相关的 IoT 中心指标，以便对发送的消息有个大致了解。 还可以创建一个诊断设置，以便将 IoT 中心资源日志中路由的操作发送到 Azure Monitor 日志、事件中心或 Azure 存储以进行自定义处理。 若要详细了解如何使用指标、资源日志和诊断设置，请参阅监视 IoT 中心。 有关教程，请参阅通过 IoT 中心设置和使用指标和资源日志。
如果要维护与任何路由上的查询不匹配的消息，建议同时启用回退路由。 可以按照配置的保留天数，在内置终结点中保留这些消息。
常见问题
以下是观察到的最常见的消息路由问题。 若要开始排除故障，请选择问题，了解详细步骤。
设备上的消息未按预期方式路由
若要排查此问题，请分析以下信息。
此终结点的路由指标
所有与路由相关的 IoT 中心指标都以“Routing”作为前缀。 你可以组合来自多项指标的信息来确定问题的根本原因。 例如，使用指标“路由传递数”来确定当消息与任何路由上的查询不匹配并且已禁用回退路由时传递到终结点或已删除的消息数。 检查“路由延迟”指标来观察消息传递的延迟是否稳定或增加。 延迟的增加可能表示特定终结点有问题，建议检查终结点的运行状况。 这些路由指标还具有维度，这些维度提供有关指标的详细信息，如终结点类型、特定终结点名称和消息未传递的原因。
任何操作问题的资源日志
观察“路由”诊断日志，获取有关路由和终结点操作的详细信息，或者确定错误和相关的错误代码以进一步了解问题。 例如，日志中的操作名称 RouteEvaluationError 表示由于消息格式问题而无法评估路由。 使用为特定的操作名称提供的提示来缓解此问题。 将事件记录为错误时，日志还提供有关评估失败原因的详细信息。 例如，如果操作名称是“EndpointUnhealthy”，则错误代码 403004 指示终结点空间不足。
终结点的运行状况
使用 REST API 获取终结点运行状况，以获取终结点的运行状况状态。 此 API 还提供有关消息上一次成功发送到终结点的时间、上一个已知错误、上一次发生已知错误的时间以及上一次尝试对此终结点发送的时间的信息。 使用为特定的上一个已知错误提供的缓解措施。
从内置终结点处获取消息的过程突然停止
若要排查此问题，请分析以下信息。
是否创建了新的路由？
在创建一个路由后，数据将停止流向内置终结点，除非创建了到该终结点的路由。 若要确保在添加新路由后消息继续流向内置终结点，应配置一个指向事件终结点的路由。
回退路由是否处于禁用状态？
回退路由将所有不满足任何现有路由上的任何查询条件的消息发送到与事件中心兼容的内置事件中心（消息/事件）。 如果已启用消息路由，则可以启用此回退路由功能。 如果没有到内置终结点的路由并且已启用回退路由，则仅与路由上的任何查询条件不匹配的消息将被发送到内置终结点。 此外，如果已删除所有现有路由，则必须启用回退路由，才能接收内置终结点处的所有数据。
可在 Azure 门户中使用 IoT 中心的“消息路由”边栏选项卡启用或禁用回退路由。 还可以将 Azure 资源管理器用于 FallbackRouteProperties，以将自定义终结点用于回退路由。
上一个有个 IoT 中心路由终结点的已知错误
REST API 中的 Get Endpoint Health（获取终结点运行状况）提供终结点的运行状况以及上一个已知错误，以确定终结点不正常的原因。 下表列出了最常见的错误。
| 上一个已知错误 | 说明/发生时间 | 可能的缓解操作 |
|---|---|---|
| 暂时性 | 出现暂时性错误，IoT 中心将重试该操作。 | 观察路由资源日志。 |
| InternalError | 将消息传递到终结点时出错。 | 这是一个内部异常，但也应查看路由资源日志。 |
| 未授权 | IoT 中心无权向指定终结点发送消息。 | 验证该终结点的连接字符串是否为最新。 如果已更改，请考虑在 IoT 中心上更新。 如果终结点使用托管标识，请检查 IoT 中心主体是否对目标具有所需的权限。 |
| 已中止 | 将消息写入到终结点时，将中止 IoT 中心。 | 查看受影响的终结点的中止限制。 修改终结点的配置以纵向扩展（如果需要）。 |
| 超时 | 操作超时。 | 请重试操作即可。 |
| 未找到 | 目标资源不存在。 | 请确保目标资源存在。 |
| 未找到容器 | 存储容器不存在。 | 请确保存储容器存在。 |
| 已禁用容器 | 已禁用存储容器。 | 请确保存储容器已启用。 |
| MaxMessageSizeExceeded | 消息路由的消息大小限制为 256 Kb。要路由的消息大小超过了此限制。 | 请检查是否可以通过使用更少的应用程序属性或更少的消息扩充来减小消息大小。 |
| PartitioningAndDuplicateDetectionNotSupported | 服务总线可能未启用重复检测。 | 从服务总线禁用重复检测，或考虑使用不带重复检测的实体。 |
| SessionfulEntityNotSupported | 服务总线可能未启用会话。 | 从服务总线禁用会话，或考虑使用不带会话的实体。 |
| NoMatchingSubscriptionsForMessage | 没有要编写服务总线主题消息的订阅。 | 创建要将 IoT 中心消息路由到的订阅。 |
| EndpointExternallyDisabled | 终结点未处于活动状态，因此 IoT 中心可以向其发送消息。 | 启用终结点以使其恢复为活动状态。 |
| DeviceMaximumQueueDepthExceeded | 已达到服务总线大小限制。 | 请考虑从目标事件中心删除消息，以允许将新消息引入到事件中心。 |
路由资源日志
下面是路由资源日志中记录的操作名称和错误代码。
操作名称
| 操作名称 | Level | 说明 |
|---|---|---|
| UndefinedRouteEvaluation | 信息 | 无法使用给定条件对消息进行评估。 例如，如果消息中缺少路由查询条件中的属性。 详细了解路由查询语法。 |
| RouteEvaluationError | 错误 | 由于消息格式存在问题，因此评估消息时出错。 例如，如果消息中未指定内容编码或内容类型无效，则会记录此错误。 必须在系统属性中设置这些内容。 |
| DroppedMessage | 错误 | 消息已被丢弃且未进行路由。 造成这种问题的原因可能是消息与任何路由查询都不匹配或终结点失效并且在多次重试后仍然无法传递消息等。 建议使用 REST API get endpoint health 来获取有关端点的更多详细信息。 |
| EndpointUnhealthy | 错误 | 终结点未接受来自 IoT 中心的消息，IoT 中心正在尝试重新发送消息。 建议通过 REST API get endpoint health 来观察上一个已知错误。 |
| EndpointDead | 错误 | 终结点已经有一个多小时未接收来自 IoT 中心的消息了。 建议通过 REST API get endpoint health 来观察上一个已知错误。 |
| EndpointHealthy | 信息 | 终结点正常运行，并从 IoT 中心接收消息。 此消息不会持续记录，仅当终结点再次恢复正常时才记录。 此消息表示 IoT 中心无法将消息发送到终结点，但终结点当前正常。 |
| OrphanedMessage | 信息 | 消息与任何路由都不匹配。 |
| InvalidMessage | 错误 | 由于与终结点不兼容，消息无效。 建议检查终结点的配置。 |
UndefinedRouteEvaluation 、RouteEvaluationError 和 OrphanedMessage 操作限制为每个 IoT 中心每分钟记录一次。
常见错误代码
| 错误代码 | 说明 |
|---|---|
| 401002 | IoT 中心未授权访问 |
| 413001 | 消息太大 |
| 403004 | 超过设备最大队列深度 |
| 503008 | 已中止接收链接 |
| 500000 | 泛型服务器错误 |
| 401 | 未授权 |
| 503 | 服务不可用 |
| 500001 | 服务器错误 |
| 400103 | 内容编码或内容类型无效 |
| 404001 | 找不到设备 |
后续步骤
如果需要更多帮助，可以联系 Azure 支持上的 Azure 专家。 或者，你也可以提出 Azure 支持事件。 请转到 Azure 支持站点提交请求。