Azure IoT Central 中的故障排除

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

设备连接问题

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

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

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

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

az extension add --name azure-iot

安装 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
  }
}

有关 UI 和 REST API 中的设备状态值的详细信息，请参阅 设备状态值 和 获取设备。

错误代码

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

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

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

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

详细的授权错误代码

文件上传错误代码

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

未建模的数据问题

确定设备将数据发送到 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>
  

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

导致 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 数据导出到 Blob 存储。

数据导出目标连接问题

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

数据导出缺失数据问题

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

Next steps

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

有关详细信息，请参阅什么是 Azure IoT 支持和帮助选项？