Устранение неполадок в Azure IoT Central

Статья
02/07/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
  }
}

Состояние подготовки устройства	Description	Возможная корректировка
Подготовлено	Нет каких-либо немедленно распознаваемых проблем.	Н/П
Зарегистрировано	Устройство еще не подключено к IoT Central.	Проверьте по журналам устройства наличие проблем с подключением.
Заблокировано	На устройстве заблокировано подключение к IoT Central.	На устройстве заблокировано подключение к приложению IoT Central. Разблокируйте устройство в IoT Central и повторите попытку. Дополнительные сведения см. в разделе "Значения состояния устройства".
Не утверждено	Устройство не утверждено.	Устройство не утверждено для подключения к приложению IoT Central. Утвердите устройство в IoT Central и повторите попытку. Дополнительные сведения см. в разделе "Значения состояния устройства"
Не назначенные	Устройство не назначено шаблону устройства.	Назначьте устройство шаблону устройства, чтобы IoT Central знал, как анализировать данные.

Дополнительные сведения о значениях состояния устройства в значениях состояния пользовательского интерфейса и устройства в REST API.

Коды ошибок

Если по-прежнему невозможно диагностировать, почему данные не отображаются в monitor-events, следующий шаг состоит в изучении кодов ошибок, сообщенных устройством.

Запустите на устройстве сеанс отладки или выгрузите журналы устройства. Проверьте коды ошибок, которые сообщает устройство.

В следующих таблицах указаны типовые коды ошибок и возможные действия по их устранению.

Если вы видите проблемы, связанные с потоком проверки подлинности:

Код ошибки	Description	Возможная корректировка
400	Текст запроса недействителен. Например, его нельзя проанализировать или не удается проверить объект.	Убедитесь, что вы отправляете корректный текст запроса в потоке аттестации, или используйте пакет SDK для устройства.
401	Не удается проверить маркер авторизации. Например, истек срок его действия или он неприменим к URI запроса. Этот код ошибки также возвращается на устройства как часть потока аттестации доверенного платформенного модуля.	Убедитесь, что устройство имеет корректные учетные данные.
404	Экземпляр Службы подготовки устройств или ресурс, например ресурс регистрации, не существует.	Отправьте заявку в службу поддержки клиентов.
412	`ETag` в запросе не совпадает с `ETag` существующего ресурса согласно RFC7232.	Отправьте заявку в службу поддержки клиентов.
429	Служба регулирует операции. Описание конкретных ограничений службы см. в разделе Ограничения Службы подготовки устройств к добавлению в Центр Интернета вещей.	Уменьшите частоту сообщений, разделите обязанности между большим количеством устройств.
500	Произошла внутренняя ошибка.	Отправьте заявку в службу поддержки клиентов, чтобы узнать, можно ли получить дополнительную помощь.

Подробные коды ошибок авторизации

Ошибка	Код вложенных ошибок	Примечания.
401 — не авторизовано	401002	Устройство использует недопустимые или истекшие учетные данные. DPS сообщает об этой ошибке.
401 — не авторизовано	400209	Устройство либо ожидает утверждения оператором, либо оператор заблокировал его.
401 IoTHubUnauthorized		Устройство использует маркер безопасности с истекшим сроком действия. Центр Интернета вещей сообщает об этой ошибке.
401 IoTHubUnauthorized	DEVICE_DISABLED	Устройство отключено в этом центре Интернета вещей и перемещено в другой центр Интернета вещей. Перепроизвидеть устройство.
401 IoTHubUnauthorized	DEVICE_BLOCKED	Оператор заблокировал это устройство.

Коды ошибок при отправке файла

Ниже приведен список распространенных кодов ошибок, которые могут появиться при попытке устройства отправить файл в облако. Помните, что прежде чем устройство сможет передать файл, необходимо настроить отправку файлов устройством в приложении.

Код ошибки	Description	Возможная корректировка
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>
```

Установка библиотеки 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 самонастраивающийся.

Если вы предпочитаете использовать графический пользовательский интерфейс, выберите представление IoT Central Необработанные данные, чтобы определить, не выполняется ли какое-либо моделирование.

После обнаружения проблемы может потребоваться обновить встроенное ПО устройства или создать новый шаблон устройства, моделирующий ранее несмоделированные данные.

Если принято решение создать новый шаблон, который корректно моделирует данные, перенесите устройства из старого шаблона в новый шаблон. Дополнительные сведения см. в статье Управление устройствами в приложении Azure IoT Central.

Недопустимый JSON

Если нет сообщений об ошибках, но значение не отображается, то это, вероятно, неправильно сформированный JSON в полезных данных, отправляемых устройством. Дополнительные сведения см. в разделе Полезные данные телеметрии, свойств и команд.

Вы не можете использовать команды проверки или представление необработанных данных в пользовательском интерфейсе, чтобы определить, отправляет ли устройство неправильно сформированное 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. Необходимые разрешения:

Назначение	Разрешение
Хранилище BLOB-объектов Azure	Участник данных хранилища BLOB-объектов
Служебная шина Azure	Отправитель данных Служебной шины Azure
Центры событий Azure	Отправитель данных Центров событий Azure
Azure Data Explorer	Администрирование

Если разрешения не были заданы правильно перед созданием назначения в приложении IoT Central, попробуйте удалить назначение и снова добавить его.

Настройте все виртуальные сети, частные конечные точки и политики брандмауэра.

Примечание.

Если вы используете управляемое удостоверение для авторизации подключения к месту экспорта, IoT Central не экспортирует данные с имитированных устройств.

Дополнительные сведения см. в статье "Экспорт данных".

Проблемы с подключением к назначению экспорта данных

На странице определения экспорта отображаются сведения о неудачных подключениях к назначению экспорта:

Screenshot that shows an example export error.

Проблемы с экспортом данных, отсутствующие

Экспорт данных экспортирует только данные, поступающие в приложение после включения экспорта данных. Если вам нужно экспортировать исторические данные или данные, пропущенные при временном отключении экспорта данных, можно использовать REST API IoT Central для запроса телеметрии устройства. Используйте запрос, чтобы получить отсутствующие данные, а затем добавить их в место назначения экспорта. Дополнительные сведения см. в разделе Использование REST API IOT Central для отправки запросов на устройства.

Следующие шаги

Если вам потребуется дополнительная помощь, вы можете обратиться к экспертам по Azure на форумах Microsoft Q&A и Stack Overflow. Также можно подать заявку в службу поддержки Azure.

Дополнительные сведения см. в статье Возможности получения поддержки и справки по Azure IoT.