IoT 中樞裝置和模組對應項的查詢

發行項
05/30/2024

裝置對應項與模組對應項可以包含標籤和屬性形式的任意 JSON 物件。 IoT 中樞可讓您以包含所有對應項資訊的單一 JSON 文件形式查詢裝置對應項與模組對應項。

下列是範例 IoT 中樞裝置對應項 (模組對應項與 moduleId) 的參數類似：

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

裝置對應項查詢

IoT 中樞可以將裝置對應項公開為稱為裝置的文件集合。因此，下列查詢會擷取整組裝置對應項︰

SELECT * FROM devices

注意

Azure IoT SDK 支援將大型結果分頁。

您可以使用 SELECT 子句匯總查詢的結果。例如，下列查詢會取得 IoT 中樞內的裝置總數計數：

SELECT COUNT() as totalNumberOfDevices FROM devices

使用 WHERE 子句篩選查詢結果。例如，若要收到 location.region 標記設定為 US 的裝置對應項，請使用下列查詢：

SELECT * FROM devices
WHERE tags.location.region = 'US'

使用布林運算子和算術比較來建立複雜的 WHERE 子句。例如，下列查詢擷取位於美國且遙測傳送頻率設定為比每分鐘還低的裝置對應項：

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

您也可以使用陣列常數搭配 IN 和 NIN (不在) 運算子。例如，下列查詢會擷取回報 WiFi 或有線連線的裝置對應項：

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

您通常必須識別包含特定屬性的所有裝置對應項。為了實現此目的，IoT 中樞支援 is_defined() 函式。例如，下列查詢會擷取定義 connectivity 屬性的裝置對應項：

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

請參閱 WHERE 子句一節，以取得篩選功能的完整參考。

也支援群組。例如，下列查詢會尋找處於各個遙測設定狀態的裝置計數：

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

這個群組查詢會傳回類似以下範例的結果：

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

在此範例中，三個裝置回報設定成功，兩個仍在套用設定，還有一個回報發生錯誤。

投影查詢可讓開發人員只傳回他們關心的屬性。例如，若要針對所有已中斷連線的啟用裝置，擷取其上次活動時間與裝置識別碼，請使用下列查詢：

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

該查詢的結果看起來會像下列範例：

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

模組對應項查詢

查詢模組對應項和查詢裝置對應項很類似，但使用不同的集合/命名空間；您應透過 devices.modules 進行查詢，而不是透過 devices：

SELECT * FROM devices.modules

我們不允許 devices 與 devices.modules 集合之間的聯結。如果您想要跨裝置查詢模組對應項，可以根據標籤來執行。此查詢會傳回所有裝置上具有掃描狀態的所有模組對應項：

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

此查詢會傳回具有掃描狀態的所有模組對應項，但僅以指定的裝置子集為限：

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

對應項查詢限制

重要

查詢結果最終會是一致的作業，而且應該容許最多 30 分鐘的延遲。在大部分情況下，對應項查詢會以幾秒鐘的順序傳回結果。 IoT 中樞致力於為所有作業提供低延遲。不過，由於網路狀況及其他無法預測的因素，其無法保證特定延遲。

對應項查詢的替代選項是使用取得對應項 REST API，依識別碼查詢個別裝置對應項。此 API 一律會傳回最新的值，並且具有較高的節流限制。您可以直接發出 REST API，或使用其中一個 Azure IoT 中樞服務 SDK 中的對等功能。

查詢運算式的長度上限可以是 8192 個字元。

目前僅支援在基本類型 (沒有物件) 之間進行比較，例如 ... WHERE properties.desired.config = properties.reported.config 只會在這些屬性具有基本值時才受到支援。

針對任何案例，我們建議不要依賴在對應項查詢的裝置身分識別屬性中找到的 lastActivityTime。此欄位不保證裝置狀態的精確量測計。請改為使用 IoT 裝置生命週期事件來管理裝置狀態和活動。如需如何在解決方案中使用 IoT 中樞生命週期事件的詳細資訊，請瀏覽使用事件方格來觸發動作以回應 IoT 中樞事件 (部分機器翻譯)。

注意

避免進行有關此作業最大延遲的任何假設。如需如何將延遲納入考慮來建置解決方案的詳細資訊，請參閱延遲解決方案 (部分機器翻譯)。

下一步

了解 IoT 中樞查詢語言的基本概念

共用方式為

IoT 中樞裝置和模組對應項的查詢

裝置對應項查詢

模組對應項查詢

對應項查詢限制

下一步

意見反應

其他資源