Azure IoT Central 中的疑難排解

文章
05/30/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
  }
}

裝置佈建狀態	描述	可採取的風險降低措施
已佈建	沒有立即可辨識的問題。	N/A
已註冊	此裝置尚未連線到 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']}'.

裝置必須使用裝置範本中針對任何遙測或屬性值所定義的資料類型。例如，如果裝置範本中定義的類型為布林值，但裝置傳送的是字串，則您會看到結構描述不符。下列輸出顯示範例錯誤訊息，其中裝置針對定義為 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 可能格式不正確。若要深入了解，請參閱遙測、屬性和命令承載。

您無法使用 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 命令。必要權限包括：

Destination	權限
Azure Blob 儲存體	儲存體 Blob 資料參與者
Azure 服務匯流排	Azure 服務匯流排資料傳送者
Azure 事件中樞	Azure 事件中樞資料傳送者
Azure 資料總管	管理

如果在 IoT Central 應用程式中建立目的地之前未正確設定權限，請嘗試移除該目的地，然後再新增一次。

設定任何虛擬網路、私人端點和防火牆原則。

注意

如果您使用受控識別，以授權對匯出目的地的連線，則 IoT Central 不會從模擬裝置匯出資料。

若要深入了解，請參閱匯出資料。

資料匯出目的地連線問題

匯出定義頁面會顯示匯出目的地失敗連線的相關資訊：

Screenshot that shows an example export error.

下一步

如果您需要更多協助，可以在 Microsoft Q&A 和 Stack Overflow 論壇上連絡 Azure 專家。或者，您可以提交 Azure 支援票證。

如需詳細資訊，請參閱 Azure IoT 支援與說明選項。

分享方式：