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

  • [アーティクル]

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

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 が含まれています。

デバイス ページでデバイス テンプレート 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 を使用してユーザートロールを管理する方法」をお勧めします。