IoT Hub メッセージルーティングのクエリ構文

[アーティクル]
03/18/2023

メッセージルーティングを使用すると、ユーザーは種類の異なるデータ (デバイステレメトリメッセージ、デバイスライフサイクルイベント、デバイスツイン変更イベントなど) を、さまざまなエンドポイントにルーティングできます。さらにルーティング前には、お客様にとって重要なデータを受け取れるよう、上記のデータに高度なクエリを適用することもできます。この記事では、IoT Hub メッセージルーティングのクエリ言語について説明するほか、一般的なクエリパターンをいくつか紹介します。

Note

この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイスツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。 Basic および Standard または Free レベルの IoT Hub の詳細については、「ソリューションに適した IoT Hub のレベルを選択する」を参照してください。

メッセージルーティングでは、メッセージプロパティとメッセージ本文に基づいてクエリを実行できるほか、デバイスツインのタグとプロパティに基づいてクエリを実行することもできます。メッセージ本文が JSON 形式でない場合でも、メッセージルーティングでメッセージをルーティングできますが、メッセージ本文にクエリを適用することはできません。クエリはブール式として記述されます。true の場合、クエリは成功し、すべての受信データがルーティングされます。それ以外の場合、クエリは失敗し、受信データはルーティングされません。式が null 値または未定義に評価されると、ブール false 値として処理され、IoT Hub ルートリソースログでエラーが生成されます。ルートが保存および評価されるようにするには、正しいクエリ構文を使用する必要があります。

メッセージプロパティに基づいたクエリ

IoT Hub では、各種プロトコルにおける相互運用性を確保するためにすべての device-to-cloud メッセージ用の共通形式が定義されています。 IoT Hub では、次の JSON 表現のメッセージが想定されます。すべてのユーザーのシステムプロパティが追加され、メッセージのコンテンツが特定されます。ユーザーは、アプリケーションプロパティをメッセージに選択的に追加できます。 IoT Hub の device-to-cloud メッセージでは大文字と小文字が区別されないため、一意のプロパティ名を使用することをお勧めします。たとえば、名前が同じプロパティが複数ある場合は、いずれか 1 つのプロパティだけが IoT Hub によって送信されることになります。

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

システムプロパティ

システムプロパティは、メッセージの内容とソースを識別するのに役立ちます。その一部を次の表に示します。

プロパティ	Type	説明
contentType	string	ユーザーはメッセージのコンテンツの種類を指定します。メッセージ本文に基づいてクエリを実行するには、この値を `application/JSON` に設定する必要があります。
contentEncoding	string	ユーザーはメッセージのエンコードの種類を指定します。 contentType プロパティが `application/JSON` に設定されている場合に使用できる値は、`UTF-8`、`UTF-16`、`UTF-32` です。
iothub-connection-device-id	string	この値は IoT Hub によって設定され、デバイスの ID を示します。クエリを実行するには、`$connectionDeviceId` を使用します。
iothub-connection-module-id	string	この値は IoT Hub によって設定され、エッジモジュールの ID を示します。クエリを実行するには、`$connectionModuleId` を使用します。
iothub-enqueuedtime	string	この値は IoT Hub によって設定されます。この値によって、メッセージがエンキューされた実際の時刻が UTC で表されます。クエリを実行するには、`$enqueuedTime` を使用します。
dt-dataschema	string	この値は、IoT Hub で、device-to-cloud メッセージに対して設定されます。デバイス接続で設定されたデバイスモデル ID が含まれます。クエリを実行するには、`$dt-dataschema` を使用します。
dt-subject	string	device-to-cloud メッセージを送信しているコンポーネントの名前。クエリを実行するには、`$dt-subject` を使用します。

その他の使用可能なシステムプロパティの詳細については、「IoT Hub メッセージの作成と読み取り」を参照してください。

Application properties

アプリケーションプロパティは、メッセージに追加できるユーザー定義の文字列です。これらのフィールドは省略可能です。

メッセージプロパティのクエリ式

メッセージシステムプロパティに基づくクエリには、前に $ 記号を付ける必要があります。アプリケーションプロパティに基づくクエリは、それらの名前を使用してアクセスされるので、前に $ 記号を付ける必要がありません。アプリケーションプロパティ名の先頭に $ がある場合は、まず IoT Hub によってそのアプリケーションプロパティ名がシステムプロパティ内で検索されますが、見つからないと、次にアプリケーションプロパティ内で検索されることになります。次の例は、システムプロパティとアプリケーションプロパティに対してクエリを実行する方法を示しています。

システムプロパティ contentEncoding に基づいてクエリを実行するには、次を行います。

$contentEncoding = 'UTF-8'

アプリケーションプロパティ processingPath に基づいてクエリを実行するには、次を行います。

processingPath = 'hot'

これらのクエリを結合するには、ブール式と関数を使用することができます。

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

サポートされている演算子と関数の完全な一覧が、「デバイスツイン、モジュールツイン、ジョブ、メッセージルーティングの IoT Hub クエリ言語」の「式と条件」セクションにあります。

メッセージ本文に基づいたクエリ

メッセージ本文に基づいてクエリを実行するには、メッセージが UTF-8、UTF-16、UTF-32 のいずれかでエンコードされた JSON 形式である必要があります。 contentType システムプロパティは application/JSON である必要があります。 contentEncoding システムプロパティは、そのシステムプロパティでサポートされている UTF エンコード値のいずれかである必要があります。これらのシステムプロパティが指定されていないと、IoT Hub でクエリ式がメッセージ本文に基づいて評価されません。

次の JavaScript 例では、正しい形式でエンコードされた JSON 本文を持つメッセージを作成する方法を示します。

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

C# のメッセージエンコードサンプルについては、Microsoft Azure IoT SDK for .NET で提供されている HubRoutingSample を参照してください。このサンプルは、メッセージルーティングのチュートリアルで使用されているものと同じです。 Program.cs ファイルには、ReadOneRowFromFile という名前のメソッドもあります。これは、エンコードされたファイルの 1 つを読み取り、デコードし、読み取ることができるように ASCII として書き戻します。

メッセージ本文のクエリ式

メッセージ本文に基づくクエリには、前に $body を付ける必要があります。クエリ式では、本文の参照、本文配列の参照、または複数の本文の参照を使用できます。さらにクエリ式では、本文の参照を、メッセージシステムプロパティの参照またはメッセージアプリケーションプロパティの参照と組み合わせることもできます。たとえば、以下の例はすべて有効なクエリ式です。

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

クエリおよび関数は、本文参照のプロパティでのみ実行できます。本文参照全体でクエリまたは関数を実行することはできません。たとえば、次のクエリはサポートされて "おらず"、undefined が返されます。

$body[0] = 'Feb'

ツイン通知のペイロードを変更内容に基づいてフィルター処理するには、メッセージ本文に対して次のクエリを実行します。たとえば、sendFrequency で必要なプロパティの変更があり、値が 10 より大きい場合にフィルター処理するには、次のようにします。

$body.properties.desired.telemetryConfig.sendFrequency > 10

プロパティ変更を含むメッセージをフィルター処理するには、プロパティの値に関係なく、is_defined() 関数を使用できます (値がプリミティブ型である場合)。

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

デバイスツインまたはモジュールツインに基づいたクエリ

メッセージルーティングでは、JSON オブジェクトであるデバイスツインまたはモジュールツインのタグとプロパティに対してクエリを実行できます。次の例では、デバイスツインを、タグとプロパティと共に示しています。

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Note

モジュールは、対応するデバイスからツインのタグを継承しません。デバイスモジュールから (たとえば、IoT Edge モジュールから) 送信されたメッセージのツインクエリは、対応するデバイスツインではなく、モジュールツインに対して実行されます。

ツインクエリ式

デバイスツインまたはモジュールツインに基づくクエリには、前に $twin を付ける必要があります。さらにクエリ式では、ツインのタグまたはプロパティの参照を、本文の参照、メッセージシステムプロパティの参照、メッセージアプリケーションプロパティの参照と組み合わせることもできます。クエリでは大文字と小文字が区別されないため、タグとプロパティには一意の名前を使用することをお勧めします。この推奨事項は、デバイスツインとモジュールツインの両方に適用されます。また、twin、$twin、body、$body をプロパティ名として使用しないようにすることをお勧めします。たとえば、以下の例はすべて有効なクエリ式です。

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

制限事項

ルーティングクエリでは、プロパティ名、メッセージ本文パス、またはデバイス/モジュールツインパスで空白または次の文字を使用することはできません: ()<>@,;:\"/?={}。

次のステップ

メッセージルーティングについて確認する。
メッセージルーティングのチュートリアルを試す。

IoT Hub メッセージ ルーティングのクエリ構文

メッセージ プロパティに基づいたクエリ

システム プロパティ