IoT Central REST API を使用してデバイスに対しクエリを実行する方法

[アーティクル]
05/27/2023

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 リファレンス」をご覧ください。

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)"
}

FROM 句の dtmi:eclipsethreadx:devkit:hlby5jgib2o 値は、デバイステンプレート ID です。デバイステンプレート ID を見つけるには、IoT Central アプリケーションの [デバイス] ページに移動し、テンプレートを使用するデバイスをポイントします。カードには、デバイステンプレート ID が含まれています。

ページ URL でデバイステンプレート ID を検索する方法を示すスクリーンショット。

応答には、同じデバイステンプレートを共有する複数のデバイスからのテレメトリが含まれます。この要求に対する応答は、次の例のようになります。

{
  "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 は必須であり、クエリを実行しているデバイスの種類を識別します。この句は、デバイステンプレート ID を指定します。
WHERE は省略可能であり、結果をフィルター処理できます。
ORDER BY は省略可能であり、結果を並べ替えできます。
GROUP BY は省略可能であり、結果を集計できます。

以下のセクションでは、これらの句について詳しく説明します。

SELECT 句

SELECT 句は、クエリ出力に含めるデータ値を一覧表示し、次の項目を含めることができます。

テレメトリ。デバイステンプレートのテレメトリ名を使用します。
$id デバイス ID。
$provisioned デバイスがまだプロビジョニングされている場合に示すブール値。
$simulated デバイスがシミュレートされたデバイスである場合に示すブール値。
$ts テレメトリ値に関連付けられているタイムスタンプ。

デバイステンプレートでコンポーネントが使用されている場合は、コンポーネント内で定義されているテレメトリを次のように参照します。

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

コンポーネント名は、デバイステンプレートで確認できます。

SELECT 句には、次の制限が適用されます。

ワイルドカード演算子は使用できません。
選択リストには 15 項目を超える項目を含められません。
クエリからは、最大 10,000 個のレコードが返されます。

Aliases

SELECT 句内の項目の別名を定義するには、AS キーワードを使用します。別名はクエリ出力で使用されます。クエリ内の他の場所でも使用できます。次に例を示します。

{
  "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

クエリから返される結果の数を制限するには、 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 句には、デバイステンプレート ID が含まれている必要があります。 FROM 句は、クエリを実行するデバイスの種類を指定します。

デバイステンプレート ID を見つけるには、IoT Central アプリケーションの [デバイス] ページに移動し、テンプレートを使用するデバイスをポイントします。カードには、デバイステンプレート ID が含まれています。

また、Devices - Get REST API 呼び出しを使用して、デバイスのデバイステンプレート ID を取得することもできます。

WHERE 句

WHERE 句を使用すると、値とタイムウィンドウを使用して結果をフィルター処理できます。

時間枠

指定した時間内にアプリケーションによって受信されたテレメトリを取得するには、WHERE 句の一部として WITHIN_WINDOW を使用します。たとえば、過去 1 日の温度と湿度のテレメトリを取得するには、次のクエリを使用します。

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

タイムウィンドウの値には、 ISO 8601 期間形式が使用されます。次の表に例を示します。

例	説明
PT10M	過去 10 分間
P1D	過去 1 日
P2DT12H	過去 2 日間と 12 時間
P1W	過去 1 週間
PT5H	過去 5 時間
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z'	特定の時間範囲

値の比較

テレメトリは、特定の値に基づいて取得できます。たとえば、次のクエリは、温度が 0 より高く、圧力が 50 を超え、デバイス ID が 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。

Note

IN 演算子は、テレメトリと $id でのみ動作します。

WHERE 句には、次の制限が適用されます。

1 つのクエリで最大 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 日間のテレメトリを集計します。

Note

集計できるのはテレメトリ値のみです。

ORDER BY 句

ORDER BY 句を使用すると、テレメトリ値、タイムスタンプ、またはデバイス ID でクエリ結果を並べ替えられます。昇順または降順で並べ替えを行えます。たとえば、次のクエリでは、最初に最新の結果が返されます。

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

ヒント

ORDER BY と TOP を組み合わせて、並べ替え後にクエリが返す結果の数を制限します。

制限

クエリの現在の制限は次のとおりです。

SELECT 句リスト内の項目は 15 以下です。
WHERE 句の論理操作は 10 以下です。
クエリ文字列の長さは最大で 350 文字です。
SELECT 句リストでワイルドカード ( * ) を使用することはできません。
クエリを実行すると、最大 10,000 個のレコードを取得できます。

次のステップ

これで REST API を使用してデバイスに対してクエリを実行する方法を学習したので、次のステップとしては「IoT Central REST API を使用してユーザートロールを管理する方法」をお勧めします。

次の方法で共有