Azure IoT Central의 문제 해결

아티클
03/05/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	Device Provisioning Service 인스턴스 또는 등록과 같은 리소스가 없습니다.	고객 지원팀을 통해 티켓을 제출합니다.
412	요청의 `ETag`가 RFC7232에 따라 기존 리소스의 `ETag`와 일치하지 않습니다.	고객 지원팀을 통해 티켓을 제출합니다.
429	서비스가 작업을 제한하고 있습니다. 특정 서비스 제한은 IoT Hub Device Provisioning Service 제한을 참조하세요.	메시지 빈도를 줄이고 더 많은 디바이스로 책임을 분담합니다.
500	내부 오류가 발생함.	고객 지원팀을 통해 티켓을 제출하여 더 유용하게 사용할 수 있는지 확인할 수 있습니다.

자세한 권한 부여 오류 코드

오류	하위 오류 코드	주의
401 권한 없음	401002	디바이스에서 유효하지 않거나 만료된 자격 증명을 사용하고 있습니다. DPS가 이 오류를 보고합니다.
401 권한 없음	400209	디바이스가 운영자의 승인을 기다리고 있거나 운영자가 차단했습니다.
401 IoTHubUnauthorized		디바이스가 만료된 보안 토큰을 사용하고 있습니다. IoT Hub가 이 오류를 보고합니다.
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']}'.

디바이스는 원격 분석 또는 속성 값에 대해 디바이스 템플릿에 정의된 데이터 형식을 사용해야 합니다. 예를 들어 디바이스 템플릿에 정의된 형식이 부울이지만 디바이스에서 문자열을 보내는 경우 스키마 불일치가 표시됩니다. 다음 출력은 디바이스가 double로 정의된 속성에 문자열 값을 사용하는 예제 오류 메시지를 보여줍니다.

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일 수 있습니다. 자세히 알아보려면 원격 분석, 속성 및 명령 페이로드를 참조하세요.

디바이스가 잘못된 형식의 JSON을 보내는지 감지하기 위해 UI의 유효성 검사 명령 또는 원시 데이터 뷰를 사용할 수 없습니다.

IoT Edge 버전

IoT Edge 모듈에서 호스트되는 구성 요소의 원격 분석을 올바르게 표시하려면 IoT Edge 버전 1.2.4 이상을 사용합니다. 이전 버전을 사용하는 경우 IoT Edge 모듈의 구성 요소에서 원격 분석이 _unmodeleddata로 표시됩니다.

데이터 내보내기 관리 ID 문제

관리 ID를 사용하여 내보내기 대상에 대한 연결 권한을 부여합니다. 데이터가 내보내기 대상에 도착하지 않습니다.

내보내기 대상을 구성하거나 사용하도록 설정하기 전에 다음 단계를 완료해야 합니다.

IoT Central 애플리케이션에 대한 관리 ID를 사용하도록 설정합니다. 관리 ID가 사용하도록 설정되어 있는지 확인하려면 Azure Portal에서 애플리케이션에 대한 ID 페이지로 이동하거나 다음 CLI 명령을 사용합니다.
```
az iot central app identity show --name {your app name} --resource-group {your resource group name}
```

관리 ID에 대한 권한을 구성합니다. 할당된 권한을 보려면 Azure Portal에서 앱의 ID 페이지에서 Azure 역할 할당을 선택하거나 az role assignment list CLI 명령을 사용합니다. 필요한 권한은 다음과 같습니다.

대상	Permission
Azure Blob 스토리지	Storage Blob 데이터 Contributor
Azure Service Bus	Azure Service Bus 데이터 보내는 사람
Azure Event Hubs	Azure Event Hubs 데이터 보내는 사람
Azure Data Explorer	관리자

IoT Central 애플리케이션에서 대상을 만들기 전에 사용 권한이 올바르게 설정되지 않은 경우 대상을 제거한 다음, 다시, 추가해 보세요.

가상 네트워크, 프라이빗 엔드포인트 및 방화벽 정책을 구성합니다.

참고 항목

관리 ID를 사용하여 내보내기 대상에 대한 연결 권한을 부여하는 경우 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 지원 및 도움말 옵션을 참조하세요.