IoT Hub デバイスとモジュール ツインのクエリ

デバイス ツインとモジュール ツインには、任意の JSON オブジェクトをタグおよびプロパティとして含めることができます。 IoT Hub では、すべてのツイン情報を含む 1 つの JSON ドキュメントとしてデバイス ツインとモジュール ツインにクエリを実行できます。

IoT Hub デバイス ツインのサンプルを次に示します (モジュール ツインは、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 Hub はデバイス ツインを devices という名前のドキュメント コレクションとして公開します。 たとえば、ほとんどの基本的なクエリでは、デバイス ツインのセット全体が取得されます。

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 句を作成します。 たとえば、次のクエリは、US に存在し、1 分以上の間隔でテレメトリを送信するように構成されているデバイス ツインを取得します。

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 Hub では、この目的で関数 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"
    }
]

この例では、3 つのデバイスが正常な構成を報告し、2 つは構成を適用中であり、1 つがエラーを報告しています。

プロジェクション クエリを使用すると、開発者は必要なプロパティのみを返すことができます。 たとえば、最後のアクティビティ時刻と、切断されているすべての有効なデバイスのデバイス ID を取得するには、次のクエリを使用します。

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

そのクエリの結果は、次の例のようになります。

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

モジュール ツイン クエリ

モジュール ツインに対するクエリはデバイス ツインに対するクエリと似ていますが、別のコレクションと名前空間を使用して、devices からではなく、device.modules からクエリを実行します。

SELECT * FROM devices.modules

デバイスと 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 Hub は、すべての操作の待機時間を短くするように努めています。 ただし、ネットワークの状態やその他の予測不能な要因のため、特定の待機時間を保証することはできません。

ツイン クエリの代替オプションは、get twin REST API を使用して ID で個々のデバイス ツインに対してクエリを実行することです。 この API からは常に最新の値が返されます。また、調整の上限は高くなっています。 REST API を直接発行するか、Azure IoT Hub Service SDK のいずれかで同等の機能を使用できます。

クエリ式の最大文字数は 8,192 文字です。

現時点では、比較はプリミティブ型間 (オブジェクトなし) でのみサポートされます。たとえば、... WHERE properties.desired.config = properties.reported.config は、これらのプロパティがプリミティブ値を持つ場合にのみサポートされます。

どのシナリオでも、ツイン クエリのデバイス ID プロパティに含まれる lastActivityTime に依存しないことをお勧めします。 このフィールドでは、デバイスの状態の正確なゲージは保証されません。 代わりに、IoT デバイス ライフサイクル イベントを使用して、デバイスの状態とアクティビティを管理してください。 ソリューションで IoT Hub ライフサイクル イベントを使用する方法の詳細については、「Event Grid を使用し IoT Hub のイベントに対応してアクションをトリガーする」を参照してください。

Note

この操作について最大待機時間を想定することは避けてください。 待機時間を考慮してソリューションを構築するソリューションを構築する方法の詳細については、待機時間ソリューションに関するページを参照してください。

次のステップ

• IoT Hub クエリ言語の基本を理解する