如何使用 IoT Central REST API 來查詢裝置

發行項
04/11/2024

IoT Central REST API 可讓您開發與 IoT Central 應用程式整合的用戶端應用程式。您可以使用 REST API 來查詢 IoT Central 應用程式中的裝置。以下是如何使用查詢 REST API 的範例：

取得裝置所報告的最後 10 個遙測值。
尋找處於錯誤狀態且韌體已過期的所有裝置。
來自裝置的遙測趨勢，平均為10分鐘的時段。
取得您所有控溫器裝置的目前韌體版本。

本文說明如何使用 /query API 來查詢裝置。

裝置可以將它所支援的屬性、遙測和命令分組到元件和模組中。

每個 IoT Central REST API 呼叫都需要授權標頭。若要深入瞭解，請參閱如何驗證和授權IoT Central REST API呼叫。

如需IoT Central REST API 的參考檔，請參閱 Azure IoT Central REST API 參考。

提示

您可以使用 Postman 來試用本文中所述的 REST API 呼叫。下載 IoT Central Postman 集合，並將其匯入 Postman。在集合中，您必須設定變數，例如您的應用程式子域和系統管理令牌。

若要瞭解如何使用IoT Central UI查詢裝置，請參閱如何使用數據總管來分析裝置數據。

執行查詢

使用下列要求來執行查詢：

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

查詢位於要求本文中，看起來像下列範例：

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

子 dtmi:eclipsethreadx:devkit:hlby5jgib2o 句中的 FROM 值是 裝置範本標識碼。若要尋找裝置範本標識碼，請流覽至 IoT Central應用程式中的 [裝置 ] 頁面，並將滑鼠停留在使用範本的裝置上。卡片包含裝置範本識別碼：

顯示如何在頁面 URL 中尋找裝置範本識別碼的螢幕快照。

回應包含來自多個共用相同裝置範本之裝置的遙測。此要求的回應看起來像下列範例：

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

語法

查詢語法類似於 SQL 語法，由下列子句組成：

SELECT 是必要的，並定義您想要擷取的數據，例如裝置遙測值。
FROM 為必要專案，並識別您要查詢的裝置類型。這個子句會指定裝置範本標識碼。
WHERE 是選擇性的，可讓您篩選結果。
ORDER BY 是選擇性的，可讓您排序結果。
GROUP BY 是選擇性的，可讓您匯總結果。

下列各節會更詳細地描述這些子句。

SELECT 子句

子 SELECT 句會列出要包含在查詢輸出中的數據值，而且可以包含下列專案：

遙測。使用裝置範本中的遙測名稱。
$id. 裝置識別碼。
$provisioned. 布爾值，顯示裝置是否已布建。
$simulated. 布爾值，顯示裝置是否為模擬裝置。
$ts. 與遙測值相關聯的時間戳。

如果您的裝置範本使用元件，則您會參考元件中定義的遙測，如下所示：

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

您可以在裝置樣本中找到元件名稱：

子句中 SELECT 適用下列限制：

沒有通配符運算子。
選取清單中不能有超過15個專案。
查詢最多會傳回 10,000 筆記錄。

別名

AS使用關鍵詞來定義子句中SELECT項目的別名。別名用於查詢輸出中。您也可以在查詢的其他地方使用它。例如：

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

提示

您無法在選取清單中使用另一個項目作為別名。例如，不允許 SELECT id, temp AS id...下列專案。

結果看起來像下列輸出：

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

頂端

TOP使用來限制查詢傳回的結果數目。例如，下列查詢會傳回前 10 個結果：

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

如果您沒有使用 TOP，查詢會傳回最多 10,000 個結果。

若要先排序結果，再 TOP 限制結果數目，請使用 ORDER BY。

FROM 子句

子 FROM 句必須包含裝置範本標識碼。子 FROM 句會指定您要查詢的裝置類型。

若要尋找裝置範本標識碼，請流覽至 IoT Central應用程式中的 [裝置 ] 頁面，並將滑鼠停留在使用範本的裝置上。卡片包含裝置範本識別碼：

您也可以使用裝置 - 取得 REST API 呼叫來取得裝置的裝置範本識別碼。

WHERE 子句

子 WHERE 句可讓您使用值和時間範圍來篩選結果：

時間範圍

若要在指定的時間範圍內取得應用程式所接收的遙測，請使用 WITHIN_WINDOW 作為子句的 WHERE 一部分。例如，若要擷取最後一天的溫度和濕度遙測，請使用下列查詢：

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

時間範圍值會使用 ISO 8601 持續時間格式。下表包含一些範例：

範例	描述
PT10M	過去 10 分鐘
P1D	過去一天
P2DT12H	過去 2 天和 12 小時
P1W	上週
PT5H	過去五個小時
'2021-06-13T13：00：00Z/2021-06-13T15：30：00Z'	特定時間範圍

值比較

您可以根據特定值取得遙測。例如，下列查詢會傳回溫度大於零、壓力大於 50 的所有訊息，而裝置識別碼是 sample-002 和 sample-003 之一：

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

支援下列運算子：

邏輯運算子 AND 和 OR。
比較運算子、、、、、<、<=>=、、<> 和 IN。>!==

注意

運算子 IN 只適用於遙測和 $id。

子句中 WHERE 適用下列限制：

您可以在單一查詢中使用最多 10 個運算子。
在查詢中 WHERE ，子句只能包含遙測和裝置元數據篩選器。
在查詢中，您最多可以擷取 10,000 筆記錄。

匯總和 GROUP BY 子句

聚合函數可讓您計算時間範圍內遙測數據的平均、最大值和最小值等值。例如，下列查詢會在 10 分鐘的視窗中計算裝置 sample-001 的平均溫度和濕度：

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

結果看起來像下列輸出：

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

支援下列聚合函數： SUM、 MAX、、 MIN、 COUNT、 AVG、 FIRST和 LAST。

使用 GROUP BY WINDOW 來指定視窗大小。如果您沒有使用 GROUP BY WINDOW，查詢會匯總過去 30 天內的遙測。

注意

您只能匯總遙測值。

ORDER BY 子句

子 ORDER BY 句可讓您依遙測值、時間戳或裝置標識符來排序查詢結果。您可以依遞增或遞減順序排序。例如，下列查詢會先傳回最新的結果：

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

提示

結合 ORDER BY 以 TOP 限制查詢在排序之後傳回的結果數目。

限制

查詢的目前限制如下：

子句清單中的項目不超過15個專案 SELECT 。
子句中 WHERE 不超過10個邏輯作業。
查詢字串的最大長度為 350 個字元。
您無法在子句清單中使用通配符（*）。SELECT
查詢最多可以擷取 10,000 筆記錄。

下一步

既然您已瞭解如何使用 REST API 查詢裝置，建議的下一個步驟是瞭解如何使用 IoT Central REST API 來管理使用者和角色。