Azure IoT Central 中的疑難解答

  • 發行項

本文包含裝置連線問題和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 ETag要求中的 不符合ETag現有資源的 ，依RFC7232。 向客戶支援提出票證。
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 Raw 數據 檢視來查看是否有專案正在建立模型。

Screenshot that shows the raw data view in an IoT Central application.

當您偵測到問題時，可能需要更新裝置韌體，或建立新的裝置範本來建立先前未建立模型數據的新裝置範本。

如果您選擇建立可正確建立數據模型的新範本，請將裝置從舊範本移轉至新的範本。 若要深入瞭解，請參閱 管理 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 支援和說明選項。