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

デバイスツインとモジュールツインには、タグとプロパティの両方として任意の JSON オブジェクトを含めることができます。 IoT Hub を使用すると、デバイスツインとモジュールツインを、すべてのツイン情報を含む単一の 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 は、デバイスツインをデバイスと呼ばれるドキュメントコレクションとして公開 します。たとえば、最も基本的なクエリでは、デバイスツインのセット全体が取得されます。

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 句を作成します。たとえば、次のクエリでは、米国にあるデバイスツインを取得し、テレメトリを 1 分未満で送信するように構成します。

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

IN および NIN (not in) 演算子で配列定数を使用することもできます。たとえば、次のクエリでは、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.modules からクエリを実行します。

SELECT * FROM devices.modules

devices と 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']

ツインクエリの制限事項

Von Bedeutung

クエリ結果は最終的に一貫した操作であり、最大 30 分の遅延を許容する必要があります。ほとんどの場合、ツインクエリは数秒の順序で結果を返します。 IoT Hub は、すべての操作の待機時間を短くするように努めています。ただし、ネットワークの状態やその他の予測不能な要因のため、特定の待機時間を保証することはできません。

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

クエリ式の最大長は 8192 文字です。

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

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

注

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

次のステップ

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-08-13

次の方法で共有

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

デバイス ツイン クエリ