Azure IoT 操作已知問題

本文列出你在使用 Azure IoT 操作 時可能遇到的已知問題。 本指南可協助您找出這些問題,並在可用時提供因應措施。

一般故障排除指引請參見 Troubleshoot Azure IoT 操作。

MQTT 代理程式問題

本節列出 MQTT 訊息代理程式目前的已知問題。

MQTT 代理程式資源不會顯示在 Azure 入口網站中


問題標識碼:4257


記錄簽章:N/A


在你的叢集中使用 Kubernetes 建立的 MQTT 代理伺服器資源,無法在 Azure 平台上看到。 這是預期之中的,因為使用 Kubernetes 管理 Azure IoT 操作 元件僅用於除錯和測試,目前尚不支援從裝置端同步資源到雲端。

此問題目前沒有任何因應措施。

一般連接器問題

本節列出影響所有連接器的當前已知問題。

大寫的入站端點名稱會防止裝置健康同步


問題 ID:0202


適用於:Azure IoT 操作 2610 公開預覽版,在 v1.6.0-preview.57 上回報,附有 ONVIF 連接器。


計畫於 2612 版本修正。


記錄簽章:在 Azure 入口網站活動記錄中,Microsoft.DeviceRegistry/namespaces/devices/write 因 InvalidRequestContent 而失敗:

The request body contains a duplicate JSON key '<endpoint name in lowercase>'. Each property name may appear at most once.

你可以建立一個包含大寫字母的入站端點名稱的裝置,但後續的裝置狀態寫入會失敗。 組態狀態使用小寫端點名稱,而執行時狀態則保留原始大小寫。 Azure 會拒絕因此產生的重複金鑰。

操作體驗可能回報裝置已建立並同步,而其健全狀態仍為未知。 端點的實際健全狀況與連線錯誤在 Azure 中看不到。

變通方法:在入站端點名稱中使用小寫字母、數字和連字號。 對於現有受影響的裝置,先儲存其設定、識別相依資產與工作負載,並在刪除並以小寫端點名稱重建前,預先規劃中斷。 確認狀態寫入是否成功,且在重新建立後已回報健康狀況。

Connector 無法偵測 Azure Key Vault 中裝置憑證的更新


問題編號:6514


N/A


在 2605 版本及之後版本中修正


當儲存在 Azure Key Vault 的裝置憑證更新時,連接器不會收到通知。 因此,連接器會繼續使用舊的認證,直到重新啟動為止。

變通方法:重新啟動連接器,強制它從 Azure Key Vault 取得更新的憑證。

OPC UA 連接器的問題

本節列出 OPC UA 連接器的目前已知問題。

無法在事件名稱中使用特殊字元


問題編號:1532


於 1.3.36(2603)及之後版本修正


記錄簽章: 2025-10-22T14:51:59.338Z aio-opc-opc.tcp-1-68ff6d4c59-nj2s4 - Updated schema information for Boiler#1Notifier skipped!


如果事件名稱包含特殊字元, #例如 、 %或 &,則綱目產生會失敗。 避免在事件名稱中使用這些字元,以防止結構描述產生問題。

缺少 OPC 連接器範本


發行編號:1330


於 1.4.73(2608)及之後版本修正


記錄簽章:N/A


Azure IoT 操作 實例部署預設應該安裝 OPC ConnectorTemplate。 部署完成後,Azure 入口網站缺少連接器範本,且ConnectorTemplate該資源也不存在於叢集中。

適用於媒體的連接器和 ONVIF 連接器的問題

本節列出媒體連接器和 ONVIF 連接器的目前已知問題。

ContinuousMove 報告在未移動攝影機的情況下成功


問題編號:0205


適用於:與 Azure IoT 操作公開預覽版搭配使用的正式執行前操作體驗。 尚未確定對生產運營體驗的影響。


計畫於 2612 版本修正。


記錄簽章:PTZ>ContinuousMove動作會傳回Succeeded,且結果為空:

{"Result": {}}

執行表單需要 Zoom>X ,儘管 Velocity.Zoom 在動作的請求架構中是可選的。 在沒有光學變焦的平移-傾斜攝影機上,提交表單顯示成功,但相機卻沒有移動。

變通方法:透過 Azure Resource Manager PanTilt叫用資產的 PTZ>ContinuousMove 動作,且承載包含 Zoom 但省略 executeAction。 例如,使用以下請求主體,將 Media 替換為攝影機的 >GetProfiles<media-profile-token> 動作所傳回的標記:

{
  "managementGroupName": "PTZ",
  "managementActionName": "ContinuousMove",
  "payload": {
    "ContinuousMove": {
      "ProfileToken": "<media-profile-token>",
      "Velocity": {
        "PanTilt": {
          "x": 0.3,
          "y": 0
        }
      },
      "Timeout": "PT1S"
    }
  }
}

請以 JSON 物件形式發送 payload ,而不是以 JSON 編碼的字串。 使用相機支持的移動數值,並用 PTZ>GetStatus;空的成功結果並不能確認移動。

媒體探索超出已探索裝置端點數量上限


問題 ID:5382


適用於:Azure IoT 操作 2610 公開預覽版,在 v1.6.0-preview.57 上回報,附有 ONVIF 連接器 v1.6.5。


計畫於 2612 版本修正。


日誌簽名:在 Azure 入口網站活動日誌中,Microsoft.DeviceRegistry/namespaces/discoveredDevices/write 因 InvalidRequestContent 而失敗,且 MaxProperties 的目標為 properties.endpoints.inbound,如下:

The object must not contain more than 10 properties.

ONVIF 的連接器會為每個媒體設定檔的多種傳輸產生媒體端點。 Azure 裝置登錄會拒絕超過 10 個入站端點的已發現裝置。 擁有三種媒體設定檔的相機可超過此限制。

攝影機的 ONVIF 端點可以報告「可用」,且其發現的 ONVIF 資產會出現,但包含媒體端點的發現裝置並未出現在 Azure 中。 你無法透過探索匯入這些端點來設定媒體連接器。

變通方法:手動建立一個帶有 Microsoft.Media 入站端點的裝置,使用製造商文件中相機的 RTSP 串流網址,例如 rtsp://<camera-ip>:554/<stream-path>。 透過支援的祕密參考設定憑證,然後建立媒體資產以及你需要的快照或片段串流。 請參見 「設定媒體連接器」。

秘密同步衝突


問題標識碼:0606


記錄簽章:N/A


使用秘密同步處理時,請確定秘密名稱是全域唯一的。 如果具有相同名稱的本機密碼存在,連接器可能無法擷取預期的秘密。

MQTT 的連接器問題

MQTT 連接器範本版本在更新期間不符


發行編號:1533


記錄簽章:N/A


在 2606 版本及之後版本中修正


當更新至 2605 版本時,現有的 MQTT 連接器範本可能會在入口網站中顯示不匹配的元資料版本。 若要解決此問題,請刪除並重新建立連接器範本。 或者,使用 Azure CLI 來更新連接器。

MQTT 連接器無法連接到擁有私有 IP 位址的外部 MQTT 代理商


發行編號:7791


記錄簽章:N/A


在 2607 版本及之後版本中修正


從 2605 版本開始,MQTT 連接器無法連接到使用私有 IP 位址的外部 MQTT 代理商。

數據流問題

本節列出數據流目前的已知問題。

升級因 ACR 登錄端點受眾不符而失敗


問題編號:3245


記錄簽章:N/A


如果資料流圖使用明確設定的 Azure Resource Manager(ARM)受眾或範圍的 Azure Container Registry(ACR)登錄端點,Azure IoT 操作 升級可能會失敗並回滾。 早期的文件範例使用 ARM 受眾,因此升級前運作良好的現有配置可能會受到影響。

Dataflows 操作員會記錄類似的受眾不匹配錯誤:

audience 'https://management.azure.com/' does not match the expected audience 'https://containerregistry.azure.net'

因應措施:在重試升級之前,先透過 Azure Resource Manager 更新現有的登錄端點 Azure 資源:

  • 對於系統指派的管理身分驗證,請將 https://management.azure.com/ 從 properties.authentication.systemAssignedManagedIdentitySettings.audience 變更為 https://containerregistry.azure.net。
  • 對於使用者指派的管理身分驗證,請將 https://management.azure.com/.default 從 properties.authentication.userAssignedManagedIdentitySettings.scope 變更為 https://containerregistry.azure.net/.default。

保留其他登錄端點屬性與驗證設定。 更新現有資源,而非僅更改本地部署檔案或刪除更新指令中的參數。 當 Azure 資源及其對應的叢集設定反映出新值後,再重新嘗試升級。

關於 registry 端點的設定範例,請參見 「設定 registry 端點」。

營運體驗網頁介面僅顯示來自Azure Container Registry(ACR)及 mcr.microsoft.com 的資料流圖產物


發行編號:8895


記錄簽章:N/A


即使你為非 ACR 容器登錄檔(如 GHCR)設定容器登錄端點:

  • 非 ACR 登錄檔的資料流程圖產物不會出現在操作體驗的網頁介面中,因此你無法建立使用它們的資料流程圖。

  • 在操作體驗 Web UI 的資料流程清單中,選取包含非 ACR 登錄元素的資料流程圖時,會產生類似以下的錯誤:Can't load data flow graph. The contents of this data flow graph are unavailable. Please ensure that it still exists, then work with your administrator to get 'AcrPull' access to required registry endpoints.

變通方法:你有兩個選擇:

  • 如果您不需要使用作業體驗 UI,可以使用 Azure CLI,對在 JSON 或 Bicep 檔案中定義的資料流程圖執行 CRUD 作業,而這些檔案包含來自非 ACR 登錄的構件。

  • 如果你想使用 Operations Experience 的網頁介面,可以將非 ACR 登錄檔的資料流程工件和圖表匯入 ACR 登錄檔。 想了解更多,請參閱 「推送模組到你的登錄檔」。

使用 Kubernetes 建立的資料流資源,在營運體驗的網頁介面中看不到


問題標識碼:8724


記錄簽章:N/A


在作業體驗 Web UI 中看不到使用 Kubernetes 在叢集中建立的數據流自定義資源。 這是預期之中的,因為使用 Kubernetes 管理 Azure IoT 操作 元件僅用於除錯和測試,目前尚不支援從裝置端同步資源到雲端。

此問題目前沒有任何因應措施。

無法在鏈結圖形案例中多次使用相同的圖形定義


發行編號:1352


於 1.3.36(2603)及之後版本修正


無法傳送設定


您可以使用一個資料流程圖的輸出作為另一個資料流程圖的輸入,來建立鏈結圖形案例。 不過,如果您在此案例中嘗試多次使用相同的圖形定義,則目前無法如預期般運作。 例如,當對 graph-passthrough:1.3.6 和 graph-1 使用相同的圖形定義(graph-2)時,下列程式碼會失敗。

      {
          nodeType: 'Graph'
          name: 'graph-1'
          graphSettings: {
            registryEndpointRef: dataflowRegistryEndpoint.name
            artifact: 'graph-passthrough:1.3.6'
            configuration: []
            }
      }
      {
          nodeType: 'Graph'
          name: 'graph-2'
          graphSettings: {
            registryEndpointRef: dataflowRegistryEndpoint.name
            artifact: 'graph-passthrough:1.3.6'
            configuration: graphConfiguration
            }
      }
  nodeConnections: [
      {
          from: {name: 'source'}
          to: {name: 'graph-1'}
      }
      {
          from: {name: 'graph-1'}
          to: {name: 'graph-2'}
      }
      {
          from: {name: 'graph-2'}
          to: {name: 'destination'}
      }
  ]

若要解決此錯誤,請根據需要多次將圖表定義推送至 ACR,每次針對不同的情境使用不同的名稱或標籤。 例如,在所述案例中,圖形定義需要使用不同的名稱或不同的標籤推送兩次,例如 graph-passthrough-one:1.3.6 和 graph-passthrough-two:1.3.6。

邊緣登錄問題

本區段列出邊緣登錄檔的目前已知問題。

使用者指派的身分識別組態使用錯誤的登錄服務帳戶


問題識別碼:3467


適用於:Azure IoT 操作 2610 公開預覽版。 報告於 v1.6.0-preview.57;CLI 不符也存在於 CLI 擴充套件 v2.11.2,其預覽部署設定檔使用 v1.6.0-preview.60。


計畫於 2612 版本修正。


記錄簽章:N/A


當你在受影響的預覽實例上執行 az iot ops identity assign --usage schema 時,CLI 會建立一個包含主體 system:serviceaccount:azure-iot-operations:adr-schema-registry的聯邦憑證。 預覽邊緣登錄檔是以服務帳號 aio-edge-registry執行,所以憑證與工作負載不符。

即使邊緣登錄的服務帳號沒有匹配的聯邦憑證,指令仍能回報成功。 登錄可以繼續使用其現有系統指派的身分識別,遮蔽設定不相符的情況。

因應措施:

  1. 在用於邊緣登錄的使用者指派管理身份上,加入一個包含以下數值的聯邦憑證:
    • 發行者: 連接叢集的 OIDC 發行者網址。
    • 主題:system:serviceaccount:azure-iot-operations:aio-edge-registry適用於預設命名空間。 如果你用其他命名空間,請替換成實際的命名空間。
    • 對象:api://AzureADTokenExchange。
  2. 確認憑證是否與 edge registry pod 使用的服務帳號相符。 如果你需要重新啟動預覽 registry,它的 StatefulSet 是 aio-edge-registry,不是 adr-schema-registry。

新增此憑證可修正信任不匹配,但執行中的登錄服務是否已採用身分變更,仍在另行調查中。 新增認證並不會確認登錄已切換身分識別。 也正在調查如何在多個使用者指派的身分識別之間進行選取。

管理動作問題

本節列出目前已知的管理行動問題。

啟用管理操作後,Event Grid 訂閱並不會立即準備好


問題編號:0208


適用於:Azure IoT 操作 2610 公開預覽版上的 CLI 擴充 v2.11.0,報告於 v1.6.0-preview.57。


計畫於 2612 版本修正。


日誌簽名:資料流 Pod 會記錄訂閱失敗,事件網格命名空間的指標 Mqtt.FailedSubscriptionOperations 會回報 Error=AuthorizationError。


此az iot ops mgmt-actions enable指令會在指派事件網格、TopicSpaces 的 Publisher 與 Subscriber 角色之前,建立請求資料流圖。 圖形可在授權前嘗試訂閱。 它會以退避方式重試,授權失敗在 CLI 回報成功後仍可能短暫持續。

管理操作可能要等到請求圖的訂閱成功後才會到達 Edge。

因應措施:在az iot ops mgmt-actions enable返回後等待約一分鐘,再發送第一個動作。 檢查要求圖形的記錄,以確認其訂閱成功。 若授權失敗持續發生,請確認所需角色指派,並預留額外時間讓角色指派生效。 不要自動重播執行結果未知的非冪等執行行動。

聯邦身分問題

本節列出聯邦身份的當前已知議題。

聯邦身份憑證發行者不匹配可能導致秘密同步認證失敗


發行編號:1190


在 2607 版本及之後版本中修正


日誌簽名:類似 AADSTS700211: No matching federated identity record found for presented assertion issuer 'https://northamerica.oic.prod-arc.azure.com/1f5f7baf-633d-4eb5-9be1-8cf1e9c6fcc9/f512e8f6-0c47-48a1-91f3-aeb5422dd766'. Please check your federated identity credential Subject, Audience and Issuer against the presented assertion.


Azure IoT 操作 在從 Azure Key Vault 取得秘密時遇到 401 未授權錯誤。

根本原因:錯誤發生是因為聯邦身份憑證(Federated Identity Credential)發行者的 URL 與 Kubernetes 服務帳號令牌中的發行者(ISS)聲明不符。

當 az iot ops secretsync enable 命令在 Azure IoT 操作 用來存取 Azure Key Vault 的使用者指派受控識別上建立聯邦身分識別認證 (FIC) 時,會將 FIC 的簽發者 URL 設為叢集的 OIDC 簽發者 URL。 在某些部署中,此 URL 包含結尾斜線 ('/'),而叢集發行之服務帳號代碼的 iss (簽發者) 宣告則會省略該斜線。

由於此問題會影響密鑰擷取期間的代碼交換,因此當您執行az iot ops secretsync enable時,通常不會發生失敗。 相反地,當 Azure IoT 操作 嘗試存取秘密時,問題才會浮現,這會使根本原因難以辨識。

變通方法:確認聯邦身份憑證上設定的發行者網址沒有斜杠結尾。 如果是,請更新同盟識別憑證,移除結尾的斜線。

你可以使用 Azure CLI az identity federated-credentials 指令來查看並在必要時更新聯邦身份憑證發行者的值,例如:

az identity federated-credential show --name <fic-name> --identity-name <managed-identity-name> --resource-group <resource-group-name>

az identity federated-credential update --name <fic-name> --identity-name <managed-identity-name> --resource-group <resource-group> --issuer <new-issuer-url-without-trailing-slash>

最佳做法是在設定期間,於執行 az iot ops secretsync enable 指令後進行此驗證,以協助避免日後可能難以診斷的驗證失敗。

模型上下文協定(MCP)問題

本節列出MCP目前已知的問題。

啟用 MCP 時,使用客戶管理憑證的部署會失敗


問題 ID:3314


適用於:Azure IoT 操作 2610 公開預覽版。


計畫於 2612 版本修正。


記錄簽章:N/A


當你自備憑證發行者時,啟用 MCP 時 Azure IoT 操作 部署會失敗。 MCP 元件會參考預設憑證發行者和信任套件,而不是你設定的資源。

變通方法:若要使用客戶管理的憑證評估其他 Azure IoT 操作 功能,請在部署組態中Disabled明確將 設為 features.mcp.mode。 MCP 預設已啟用。 請參閱停用 MCP以了解組態設定。