ルールクエリの詳細な作成ルール
ルールクエリを作成するためには、基本的なSQL構文を理解しなければなりません。SELECT構文だけをサポートしているので、SELECT - FROM - WHERE順で作成する必要があります。 ルールクエリ作成のルールは、次の通りです。
SELECT [<トピックAlias> <メッセージJSON Key1>、<トピックAlias> <メッセージJSON Key2>、...]FROM "[トピック]" AS [トピックAlias] WHERE [条件]
例
JSONメッセージ
{ "deviceId": "1", "deviceType": "illumination", "buildingId": "N1001", "roomId": "001", "light": 75, "battery": 3.3, "eventTime": "2020-01-01 00:00:00" }
照明の明るさが50lux未満であるデータのメッセージ内の全フィールドを抽出
SELECT * FROM "apt/+/sensor/light" AS t WHERE t.light < 50
特定の建物の照明の明るさが50lux未満であるデータのメッセージ内の特定フィールドのみ抽出
SELECT t.light, t.buildingId, t.roomId, t.eventTime FROM "apt/#" AS t WHERE t.buildingId = 'N1001' AND t.light < 50
SELECT/WHERE 節
一般的なSQLクエリと同様に作成が可能であり、SELECT * FROM ...のように *(アスタリスク)の使用が可能です。
GROUP BY / ORDER BY / DISTINCT / JOIN / UNION / UNION ALL / INTERSECT / LIMITなど複数のデータを処理するクエリはサポートしていません。
SUBQUERYはサポートしていません。
MQTTに送信したJSONメッセージのKey(ex:light、buildingId、...)を使用して、特定のKeyに対応する値をクエリの結果として選択することができます。
組み込み関数または算術演算式など、JSONフィールドKeyをそのまま使用しない場合、Aliasを使用して、結果の値として使用するJSONフィールドKeyを指定することをお勧めします。Aliasがない場合、クエリの結果のJSONフィールドKeyは、SELECT節での位置に基づいて、 _1, _2, ..., _n のように出力されます。
例
クエリ (t.weight / 1000.0と t.weight * 0.0352にはAliasがないので、SELECT節の3番目の位置は_3、4番目の位置は_4で表示されます。)
SELECT t.productId, t.weight AS gram, t.weight / 1000.0, t.weight * 0.0352, t.weight / 1000.0 AS kg, t.weight * 0.0352 AS oz FROM "scm/warehouse/001" AS t
結果JSON
{ "productId":"23", "gram":1500, "_3":1.5, "_4":52.8, "kg":1.5, "oz":52.8 }
サポートするトリガークエリの組み込み関数は、[[アドオン]ページのルールクエリの組み込み関数](./cloudiotcore_setting.md#ルールクエリの組み込み関数)で確認できます。
FROM節
- 1つのMQTT トピックのみ可能です。
- トピック名の最大文字数は255文字です。
- "(Double Quotes)を利用して、トピックを括って表現しなければなりません。
- SELECTまたはWHERE節に、トピック名と同じJSONフィールドKeyがある場合、トピックは必ずAlias(別名)を指定しなければならず、[トピックAlias].[JSONフィールドKey]の形式で作成する必要があります。
- ピックのレベルは、/(スラッシュ)で区切らなければなりません。
- トピックはアルファベットの大文字小文字、数字、空白, !@$%^&()_-={[}]?><\/`' の文字が可能です。
- .(ピリオド), *(アスタリスク), "(Double Quotes)はトピックに含めることができません。
- トピックは、/または//にはなり得ません。
- マルチレベルのワイルドカード #(ハッシュタグ)は、最終的なレベルでのみ使用することができます。
- 単一レベルのワイルドカード+(プラス)は、すべてのレベルで使用可能です。
- ワイルドカードは、該当のレベルにおいて単独で使用しなければなりません。他の文字とあわせて使用することはできません。
- ルールに既に登録されているメッセージ再発行アクションがある場合、メッセージ再発行アクションによって、再度ルールルールクエリにルールクエリされるトピックでの設定はできません。
その他のルール
文字列
関数、比較文などの文字列を使用する場合、'(Single Quote)で括らなければなりません。
例
JSONメッセージのdeviceTypeフィールドの値と文字列のsensor比較
SELECT * FROM "factory/room1/temparature" WHERE deviceType = 'sensor'
JSONフィールドKey
クエリでJSONフィールドKeyを使用しますが、入力メッセージに該当するJSONフィールドKeyがない場合は、クエリエラーが発生します。クエリエラーはエラーアクションで確認できます。
例
JSONメッセージのdevice、voltフィールドの値がないエラーが発生
SELECT device FROM "factory/room1/temparature" WHERE volt = 1.5
{ "lux": 1 }
"(Double Qutoes)を利用して、JSONフィールドKeyを使用していることを明示させることもできます。下のような場合、必ずフィールドKeyを"(Double Qutoes)で括らなければなりません。
JSONフィールドKeyの大文字と小文字を区別する必要がある場合
- JSONメッセージが以下の場合、クエリでdeviceTypeは大文字小文字の区別をしないので、"(Double Qutoes)で括らないとき、どのJSONフィールドKeyを選択すべきかわからないため、クエリエラーが発生します。
{ "deviceType": 10,"DEVICEType": 5 }
SELECT deviceType FROM "factory/room1/temparature" WHERE deviceType = 10
Multiple matches were found for the specified identifier Evaluator Error
- JSONメッセージが以下の場合、クエリでdeviceTypeは大文字小文字の区別をしないので、"(Double Qutoes)で括らないとき、どのJSONフィールドKeyを選択すべきかわからないため、クエリエラーが発生します。
JSONフィールドKeyが、Keywordで使用される単語である場合
ルールクエリを検証するとき、JSONフィールドKeyが、クエリ文で使用できない予約されたKeywordと同じであれば、以下のようなエラーが発生します。Keywordと同じJSONフィールドKeyを使用するためには"(Double Quotes)で括ってJSONフィールドKeyであることを明示しなければなりません。
Unexpected keyword
例(timeはクエリ文でKeywordなので「time」JSONフィールドキーを使用するために「time」を使用)
SELECT "time" FROM "factory/room1/temparature"
JSONメッセージのネストフィールドへのアクセスではなく、JSONフィールドKeyの.(ピリオド)が含まれている場合、または特殊文字を含むJSONフィールドKeyの場合。
ルールクエリでフィールドの.(ピリオド)は、JSONメッセージ内のネストフィールドを意味します。JSONフィールドKeyに.(ピリオド)が含まれている場合、"(Double Quotes)で括ってフィールドKey値の特殊文字として処理することができます。
例
メッセージの内容
{ "deviceId": "1", "deviceType": "sensor", "temperature": 21.3, "device.serialNo": 100001, "manufacture": { "company": "myCompany", "buildDate": "2020-01-01" } }
ネストフィールドの照会
SELECT manufacture.company FROM "factory/room1/temparature"
.(ピリオド)が含まれているフィールドの照会
SELECT "device.serialNo" FROM "factory/room1/temparature"
特殊文字を含むJSONフィールドKeyがある場合
SELECT * FROM "factory/room1/temparature" WHERE "deviceType@number" = "sensor"
制限事項
接続の制限事項
- 現在はMQTTプロトコルTLSバージョン1.0、1.1、1.2の通信をサポートし、8883ポートを利用しなければなりません。
メッセージの制限事項
- メッセージのトピックで.(ピリオド)は、MQTTのレベル区切り文字/(スラッシュ)の役割をし、 *(アスタリスク)は、MQTTの+(ワイルドカード)の役割をします。2つの特殊文字は、トピック内に含まれないことをお勧めします。
仮想デバイスの制限事項
- 仮想デバイス名は、最大128文字に制限されています。
- 仮想デバイス名は、重複して登録することはできません。
- 仮想デバイス名には、英大文字、英小文字、数字、-(ハイフン)、_(アンダースコア)のみ使用できます。
- 属性は、最大10個まで入力できます。
- 属性Keyは、重複して登録することはできません。
- 属性Keyは128文字以内で、英大文字、英小文字、数字、-(ハイフン)、_(アンダースコア)のみ使用できます。
- 属性Valueは512文字以内で、英大文字、英小文字、数字、-(ハイフン)、_(アンダースコア)のみ使用できます。
属性テンプレートの制限事項
- 属性テンプレート名は、重複して登録することはできません。
- 属性テンプレート名は128文字以内に制限されており、英大文字、英小文字、数字、-(ハイフン)、_(アンダースコア)のみ使用できます。
- 属性テンプレートKeyは、最大10個まで入力できます。
- 属性テンプレートKeyは、重複して登録することはできません。
- 属性Keyは128文字以内で、英大文字、英小文字、数字、-(ハイフン)、_(アンダースコア)のみ使用できます。
ルールの制限事項
入力の制限事項
- ルールの名前が同じである重複の登録はされません。
- ルール名は、英大文字、英小文字、数字, - (ハイフン)、_(アンダースコア)でなければなりません。
- ルール名は、最大128文字に制限されています。
- ルール名は、最大255文字に制限されています。
- ルールクエリは、最大255文字に制限されています。
- ルールは、ユーザーごとに最大100個まで作成することができます。
- 無効化したルールの場合、ルールとルールに含まれるアクションは、無効化されて動作しません。
- ルールを作成するときの制限事項は、[ルールクエリの詳細な作成ルールを参照してください。
性能の制限事項
- ルールに含まれるメッセージは、5KByteを超えることはできず、必ずJSONオブジェクトでなければなりません。JSON Listはサポートしていません。
- ルールに含まれるメッセージのトピックの最大文字数は255文字です。これ以外のメッセージはルールクエリされません。
- ルール処理で含まれるメッセージは、毎秒10,000個を超えることができません。より多く含まれるメッセージの場合、処理遅延が発生します。
- メッセージのルール処理、アクションの実行順序は3秒以内で、順序は保障しません。
- 処理遅延時間は平均3秒であり、ルールの数、クエリの種類、アクションの種類に応じて、遅延時間が追加で発生することがあります。
アクションの制限事項
アクションの種類による制限事項
アクション
- 少なくとも1個、最大5個まで登録可能です。
エラーアクション
- 最大1個が登録可能です。
アクションの連携商品別の制限
指定したトピックに再発行
- MQTTの再発行アクションのトピックは、ルールクエリのFROM節トピックに含まれるように設定することができません。
- トピックはアルファベットの大文字小文字、数字、空白, !@$%^&()_-={[}]?><\/`' の文字が可能です。
CLOUD FUNCTIONSにデータを転送
- Cloud Functions商品に登録されたトリガーのみ使用できます。 実際にロジックを実行するCloud Functionsアクションを作成し、必ずCloud Functionsトリガーに接続することでCloud Functionsアクションを実行できます。
- Cloud Functionsのトリガーのうち、Cloud IoTトリガータイプのトリガーのみ登録できます。
- Cloud Functionsの実行エラーが発生すると、Cloud IoT Coreでメッセージの処理が遅延することがあります。
- バッチ時間の設定は、最小5秒から最大600秒(10分)までサポートします。
- Cloud Functionsアクションに伝達されるパラメータのサイズは、1MBに制限されます。 バッチ時間内に当該サイズを超える場合、Cloud Functionsアクションをすぐに実行します。
参考
- Cloud IoT Core商品のアップデート時に、コネクションが切断されることがあります。コネクションが途切れる場合、再度接続する必要があります。
- MQTT接続の特性上、ネットワーク接続が安定せずコネクションが切断されることがあります。再接続が必要になることがあります。