你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure IoT Central 中的故障排除

项目
03/11/2024

本文包括有关 IoT Central 应用程序中设备连接问题和数据导出配置问题的故障排除指南。

设备连接问题

本部分可帮助确定你的数据是否可以到达 IoT Central。

安装 az cli 工具和 azure-iot 扩展（如果尚未安装）。

要了解如何安装 az cli，请参阅安装 Azure CLI。

要安装azure-iot 扩展，请运行以下命令：

az extension add --name azure-iot

注意

首次运行扩展命令时，系统可能会提示您安装 uamqp 库。

安装 azure-iot 扩展后，请启动设备，查看设备发送的消息是否能够到达 IoT Central。

使用以下命令登录到你的 IoT Central 应用程序的订阅：

az login
az account set --subscription <your-subscription-id>

要监视设备正在发送的遥测数据，请使用以下命令：

az iot central diagnostics monitor-events --app-id <iot-central-app-id> --device-id <device-name>

如果设备已成功连接到 IoT Central，会看到类似于以下示例的输出：

Monitoring telemetry.
Filtering on device: device-001
{
    "event": {
        "origin": "device-001",
        "module": "",
        "interface": "",
        "component": "",
        "payload": {
            "temp": 65.57910343679293,
            "humid": 36.16224660107426
        }
    }
}

要监视设备与 IoT Central 交换的属性更新，请使用以下预览命令：

az iot central diagnostics monitor-properties --app-id <iot-central-app-id> --device-id <device-name>

如果设备成功发送属性更新，会看到类似于以下示例的输出：

Changes in reported properties:
version : 32
{'state': 'true', 'name': {'value': {'value': 'Contoso'}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac
': 200}, 'brightness': {'value': {'value': 2}, 'status': 'completed', 'desiredVersion': 7, 'ad': 'completed', 'av': 7, 'ac': 200}, 'p
rocessorArchitecture': 'ARM', 'swVersion': '1.0.0'}

如果你看到数据显示在终端中，则表明数据能够到达你的 IoT Central 应用程序。

如果在几分钟后看不到任何数据，请尝试按键盘上的 Enter 或 return 键，以防输出停滞。

如果终端上仍未显示任何数据，则可能是设备出现网络连接问题，或者没有正确地将数据发送到 IoT Central。

检查设备的预配状态

如果 CLI 监视器上未显示数据，请运行以下命令检查设备的预配状态：

az iot central device registration-info --app-id <iot-central-app-id> --device-id <device-name>

以下输出显示了导致设备无法连接的示例：

{
  "@device_id": "v22upeoqx6",
  "device_registration_info": {
    "device_status": "blocked",
    "display_name": "Environmental Sensor - v22upeoqx6",
    "id": "v22upeoqx6",
    "instance_of": "urn:krhsi_k0u:modelDefinition:w53jukkazs",
    "simulated": false
  },
  "dps_state": {
    "error": "Device is blocked from connecting to IoT Central application. Unblock the device in IoT Central and retry. Learn more:
https://aka.ms/iotcentral-docs-dps-SAS",
    "status": null
  }
}

设备预配状态	说明	可能的缓解操作
已预配	无立即可识别的问题。	空值
已注册	设备尚未连接到 IoT Central。	检查设备日志以确认连接问题。
已阻止	设备被阻止连接到 IoT Central。	设备被阻止连接到 IoT Central 应用程序。在 IoT Central 中取消阻止设备，然后重试。若要了解详细信息，请参阅设备状态值。
未获得批准	设备未获批准。	设备未获得连接到 IoT Central 应用程序的批准。在 IoT Central 中批准设备，然后重试。若要了解详细信息，请参阅设备状态值
未分配	设备不会分配给设备模板。	将设备分配到设备模板，以便 IoT Central 知道如何分析数据。

详细了解UI 中的设备状态值和REST API 中的设备状态值。

错误代码

如果仍无法诊断 monitor-events 中不显示数据的原因，下一步是查找设备报告的错误代码。

在设备上启动调试会话，或从设备收集日志。检查设备报告的任何错误代码。

下表显示了常见错误代码和可能有效的缓解操作。

如果你看到与身份验证流相关的问题：

错误代码	说明	可能的缓解操作
400	请求正文无效。例如，无法进行分析，或者对象无法验证。	请确保在证明流中发送正确的请求正文，或者使用设备 SDK。
401	无法验证授权令牌。例如，令牌已过期或不适用于请求的 URI。此错误代码也会在 TPM 证明流中返回给设备。	确保你的设备具有正确的凭据。
404	设备预配服务实例或某个资源（如注册）不存在。	向客户支持提交票证。
412	根据 RFC7232 规范，请求中的 `ETag` 与现有资源中的 `ETag` 不匹配。	向客户支持提交票证。
429	服务正在限制操作。对于具体的服务限制，请参阅 IoT 中心设备预配服务限制。	减少消息频率，将职责分给更多设备。
500	发生内部错误。	向客户支持部门提交票证，看看客户支持部门能否进一步提供帮助。

详细的授权错误代码

错误	子错误代码	说明
401 未授权	401002	设备正在使用无效或已过期的凭据。 DPS 报告此错误。
401 未授权	400209	设备正在等待操作员批准，或者操作员已阻止该设备。
401 IoTHubUnauthorized		设备正在使用过期的安全令牌。 IoT 中心报告此错误。
401 IoTHubUnauthorized	DEVICE_DISABLED	已在此 IoT 中心禁用设备，并将其移动到其他 IoT 中心。重新预配设备。
401 IoTHubUnauthorized	DEVICE_BLOCKED	操作员阻止了此设备。

文件上传错误代码

下面是在设备尝试将文件上传到云时可能会看到的常见错误代码的列表。请记住，在设备可以上传文件之前，必须先在应用程序中配置设备文件上传。

错误代码	说明	可能的缓解操作
403006	已超出并发文件上传操作的数量。每个设备客户端仅限 10 个并发文件上传。	确保设备立即通知 IoT Central 文件上传操作已完成。如果这不起作用，请尝试减少请求超时。

未建模的数据问题

确认你的设备将数据发送到 IoT Central 后，下一步是确保你的设备以有效格式发送数据。

要检测问题的类别，请针对你的情况运行最适合的 Azure CLI 命令：

要验证遥测数据，请使用预览命令：

az iot central diagnostics validate-messages --app-id <iot-central-app-id> --device-id <device-name>

若要验证属性更新，请使用预览命令：

az iot central diagnostics validate-properties --app-id <iot-central-app-id> --device-id <device-name>

首次运行 validate 命令时，系统可能会提示您安装 uamqp 库。

导致 IoT Central 中不显示设备数据的三种常见问题类型包括：

设备模板与设备数据不匹配。
数据是无效的 JSON。
IoT Edge 的旧版本会导致来自组件的遥测数据错误地显示为未建模数据。

设备模板与设备数据不匹配

对于设备发送的有效负载中的任何遥测数据字段名称，设备必须使用与设备模板中相同的名称和大小写。以下输出显示了一个示例警告消息，其中设备发送的遥测数据值为 Temperature，但该值应为 temperature：

Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[WARNING] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['Temperature']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

对于设备发送的有效负载中的任何属性名称，设备必须使用与设备模板中相同的名称和大小写。以下输出显示了一个示例警告消息，其中 osVersion 属性未在设备模板中定义：

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
[WARNING]  [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg] Device is sending data that has not been defined in the device template. Following capabilities have NOT been defined in the device template '['osVersion']'. Following capabilities have been defined in the device template (grouped by components) '{'thermostat1': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'thermostat2': ['temperature', 'targetTemperature', 'maxTempSinceLastReboot', 'getMaxMinReport', 'rundiagnostics'], 'deviceInformation': ['manufacturer', 'model', 'swVersion', 'osName', 'processorArchitecture', 'processorManufacturer', 'totalStorage', 'totalMemory']}'.

对于任何遥测数据值或属性值，设备必须使用设备模板中定义的数据类型。例如，如果设备模板中定义的类型为布尔值，但设备发送的是字符串，则会看到架构不匹配。以下输出显示了一个示例错误消息，其中设备对定义为双精度的属性使用字符串值：

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus
Validating telemetry.
Filtering on device: sample-device-01.
Exiting after 300 second(s), or 10 message(s) have been parsed (whichever happens first).
[ERROR] [DeviceId: sample-device-01] [TemplateId: urn:modelDefinition:ofhmazgddj:vmjwwjuvdzg]  Datatype of telemetry field 'temperature' does not match the datatype double. Data sent by the device : curr_temp. For more information, see: https://aka.ms/iotcentral-payloads

如果同一遥测数据名称在多个接口中定义，但设备不符合 IoT 即插即用规范，则这些验证命令还会报告错误。

如果希望使用 GUI，请使用 IoT Central 的“原始数据”视图，查看是否有些内容没有建模。

检测到问题后，你可能需要更新设备固件，或创建一个新的设备模板来对以前未建模的数据进行建模。

如果选择创建可正确对数据建模的新模板，请将设备从旧模板迁移到新模板。要了解详细信息，请参阅“在 Azure IoT Central 应用程序中管理设备”。

无效 JSON

如果未报告任何错误，但未显示值，则设备发送的有效负载中可能存在格式错误的 JSON。有关详细信息，请参阅遥测、属性和命令有效负载。

无法在 UI 中使用验证命令或“原始数据”视图来检测设备是否发送格式错误的 JSON。

IoT Edge 版本

若要正确显示来自 IoT Edge 模块中承载的组件的遥测数据，请使用 IoT Edge 版本 1.2.4 或更高版本。如果使用早期版本，来自 IoT Edge 模块中组件的遥测数据会显示为“_unmodeleddata”。

数据导出托管标识问题

你使用的是托管标识来对导出目标的连接进行授权。数据未到达导出目标。

在配置或启用导出目标之前，请确保完成以下步骤：

为 IoT Central 应用程序启用托管标识。要验证是否已启用托管标识，请转到 Azure 门户中应用程序的标识页或使用以下 CLI 命令：
```
az iot central app identity show --name {your app name} --resource-group {your resource group name}
```

为托管标识配置权限。要查看分配的权限，请在 Azure 门户的应用的标识页上选择“Azure 角色分配”，或使用az role assignment list CLI 命令。所需权限包括：

目标	权限
Azure Blob 存储	存储 Blob 数据参与者
Azure 服务总线	Azure 服务总线数据发送方
Azure 事件中心	Azure 事件中心数据发送方
Azure 数据资源管理器	管理员

如果在 IoT Central 应用程序中创建目标之前未正确设置权限，请尝试删除目标，然后再次添加。

配置任意虚拟网络、专用终结点和防火墙策略。

注意

如果使用托管标识授权连接到导出目标，IoT Central 不会从模拟设备导出数据。

若要了解详细信息，请参阅导出数据。

数据导出目标连接问题

导出定义页显示与导出目标连接失败的信息：

Screenshot that shows an example export error.

数据导出缺失数据问题

数据导出仅导出在启用数据导出后到达应用程序的数据。如果需要导出历史数据或数据导出暂时关闭时缺失的数据，可以使用 IoT Central REST API 查询设备遥测数据。使用查询检索缺失的数据，然后将数据添加到导出目标。若要了解详细信息，请参阅如何使用 IoT Central REST API 查询设备。

后续步骤

如果需要更多帮助，可以通过 Microsoft Q&A 和 Stack Overflow 论坛联系 Azure 专家。或者，你也可以提交 Azure 支持票证。

有关详细信息，请参阅 Azure IoT 支持和帮助选项。

通过