Azure IoT Hubのデバイスツインを使ってタグをつけてクエリするメモ

## はじめに

Azure IoT Hub のデバイスツインの 3 つの機能のうち、タグについてのメモです。

- 必要なプロパティ（Desired properties）
- 報告されるプロパティ（Reported properties）
- タグ（Tags）

## 公式ドキュメント

https://docs.microsoft.com/ja-jp/azure/iot-hub/iot-hub-devguide-device-twins

https://docs.microsoft.com/ja-jp/azure/iot-hub/tutorial-device-twins

## デバイスツインとは

> "デバイスツイン" は、デバイスの状態に関する情報 (メタデータ、構成、状態など) を格納するJSONドキュメントです。
> Azure IoT Hub は、IoT Hubに接続する各デバイスにデバイスツインを保持します。

デバイスツインの実態は JSON ドキュメントです。
IoT Hub に接続(登録)しているデバイスごとに JSON ドキュメントが生成されます。

## デバイスツインのタグとは

> タグはバックエンド アプリケーションによって設定され、デバイスに送信されることはありません。 
> タグはデバイスの整理に使用します。

タグを使ってデバイスを整理できます。
どのデバイスをどこに設置したか、などの情報を付与しておくと便利です。

## Azureポータルでデバイスツインを開く

`IoT Hub > IoTデバイス > 対象のデバイス > デバイスツイン`から開けます。

<a href="https://gyazo.com/d893cc7315034c184304dc081236beb5"><img src="https://i.gyazo.com/d893cc7315034c184304dc081236beb5.png" alt="Image from Gyazo" width="1145"/></a>
<a href="https://gyazo.com/a942408dd2d74fa204243e44827463b4"><img src="https://i.gyazo.com/a942408dd2d74fa204243e44827463b4.png" alt="Image from Gyazo" width="1145"/></a>
<a href="https://gyazo.com/e897b0f5f12750ceedf1754fac694696"><img src="https://i.gyazo.com/e897b0f5f12750ceedf1754fac694696.png" alt="Image from Gyazo" width="1145"/></a>

## タグを設定する

タグは、デバイスツインの`"tags"`プロパティに設定します。
今回は試しに自宅のセンサーを整理するためのの 3 つのプロパティを設定してみます。

- area：設置エリア
- room：部屋
- sensing-target：センサーの種類（温度・湿度 etc...）

先程開いたデバイスツインのページではそのまま JSON を編集できます。
トップレベルに以下のプロパティを追加します。

```json
    "tags": {
        "location": {
          "area": "tokyo",
          "room": "living-room"
        },
        "sensingTarget": "temperature"
    },
```

(JSON 全量は[こちら](https://gist.github.com/tmitsuoka0423/0106b4393eda61c564c0b6c5cdeb77b8))

追加するとこんな感じです。`保存`を忘れずにクリックしましょう。
<a href="https://gyazo.com/169d2e835cd297e94dcfa7439336bccf"><img src="https://i.gyazo.com/169d2e835cd297e94dcfa7439336bccf.png" alt="Image from Gyazo" width="1145"/></a>
ちなみに、タグのネストは 10 段階までいけます。大体のケースでは十分足りるでしょう。

## タグをつけたデバイスを見つける

IoT Hub には、大量のデバイスの中から対象のデバイスを見つけるために、SQL に似たクエリ言語が用意されています。

https://docs.microsoft.com/ja-jp/azure/iot-hub/iot-hub-devguide-query-language

### デバイスをクエリする方法

IoTHub ポータル上でデバイスをクエリする方法は 2 つあります。

1. クエリエクスプローラーを使う
2. クエリビルダーを使う

今回は簡単に利用できるクエリビルダーを使ってみます。

### クエリビルダーの使い方

クエリビルダーは、`IoTHubポータル > IoTデバイス`のページ上部に表示されています。
<a href="https://gyazo.com/d06052b0df5ccf554af4b293ede8f3fa"><img src="https://i.gyazo.com/d06052b0df5ccf554af4b293ede8f3fa.png" alt="Image from Gyazo" width="1145"/></a>

使い方は以下のとおりです。

- （1）：クエリの条件を入力します（SQL でいうと WHERE 句に相当します）
- （2）：`＋`をクリックすると、AND 条件を追加できます。
- （3）：`デバイスのクエリ`をクリックして、クエリを実行します。
- (（4）：クエリを直接記入できるクエリエディターに切り替えることもできます)
<a href="https://gyazo.com/bb31eb3dfbe63ff3d5d4052357eb0d41"><img src="https://i.gyazo.com/bb31eb3dfbe63ff3d5d4052357eb0d41.png" alt="Image from Gyazo" width="855"/></a>

事前にデバイスを 3 台登録しておきました。
タグの内容はこんな感じ。

| デバイスID | location.area | location.room | sensingTarget |
| :-: | :-: | :-: | :-: |
| m5atom-lite-1 | tokyo | bed-room | temperature |
| m5atom-lite-2 | tokyo | living-room | temperature |
| m5atom-lite-3 | tokyo | bed-room | humidity|

### クエリしてみる

東京にあるデバイスを表示してみましょう。

フィールド：`tags.location.area`
値：`'tokyo'`（※`'`も必要です！）。
<a href="https://gyazo.com/330ec55ab4f91be7a2b8379f0f8e633f"><img src="https://i.gyazo.com/330ec55ab4f91be7a2b8379f0f8e633f.png" alt="Image from Gyazo" width="848"/></a>
クエリを実行します。
`location.area`に`tokyo`を登録したデバイスがすべて表示されました。
<a href="https://gyazo.com/4f7bda707165541303484255d0979806"><img src="https://i.gyazo.com/4f7bda707165541303484255d0979806.png" alt="Image from Gyazo" width="854"/></a>

続いて、気温を測るデバイスを表示してみましょう。

フィールド：`tags.sensingTarget`
値：`'temperature'`
<a href="https://gyazo.com/a56a560bd592b5b7907cf3bc5f1ef2a6"><img src="https://i.gyazo.com/a56a560bd592b5b7907cf3bc5f1ef2a6.png" alt="Image from Gyazo" width="844"/></a>
`sensingTarget`が`temperature`のデバイスのみ表示されました。

## まとめ

デバイスツインのタグを利用して、デバイスの設置場所・用途を設定しました。
また、対象のデバイスを見つけるクエリビルダーの使い方を紹介しました。