ルール

ルール（ルールエンジンとも呼ばれます）は、EMQXに組み込まれたSQLベースのデータ処理コンポーネントです。これはコネクターと連携して、コード不要でのIoTデータの抽出、フィルタリング、変換、保存、処理を可能にし、アプリケーション統合とビジネスイノベーションを加速します。

ルールの仕組み

ルールは、データソースからデータを取得し、データ変換を行い、その結果に適用すべきアクションを指定します。

rules

データソース：ルールのデータソースはメッセージ、イベント、または外部データシステムが対象です。ルールのSQLのFROM句でデータソースを指定し、WHERE句でルールが処理するメッセージに対する追加の制約を設定します。
対応するデータソースの種類やWHERE句で参照可能なフィールドの詳細は、SQLデータソースとフィールドをご参照ください。
データ変換：データ変換は入力メッセージを変換する処理を指します。SQLのSELECT部分で入力メッセージからデータを抽出・変換します。埋め込みSQLのサンプル文を使って、タイムスタンプを出力メッセージに追加するなど高度な変換も実装可能です。
構文や組み込みSQL関数の詳細は、ルールSQLリファレンスおよび組み込みSQL関数をご覧ください。SQL関数については jq関数も参考になります。
アクション：アクションは「処理済みデータをどこに送るか」という課題を解決します。EMQXブローカーに対し、ルールで生成されたデータの処理方法を指示します。入力が指定されたルールに従って処理された後、1つ以上のアクションを定義してSQL実行結果を処理します。ルールエンジンは対応するアクションを順次実行します。現在、ルールは以下の2種類のアクションをサポートしています：
- 組み込みアクション：処理結果を別のMQTTトピックに再パブリッシュするメッセージ再パブリッシュが利用可能です。
- 処理結果をデータベースに保存：事前定義されたコネクターを通じて様々なターゲットサービスへデータを送信します。

ルールSQLの例

SQL文はルールのデータソース指定とデータ処理を定義するために使用します。以下はSQL文の例です：

sql

SELECT
    payload.data as d
FROM
    "t/#"
WHERE
    clientid = "foo"

上記SQL文では：

データソース：トピックt/#からのメッセージ
データ処理：メッセージ送信者のクライアントIDがfooの場合、メッセージ内容のdataフィールドを抽出し、新しい変数dに割り当てる

TIP

.構文はデータがJSONまたはMap形式であることを前提とします。別のデータ型の場合は、SQL関数を使ってデータ型変換を行う必要があります。

ルールSQL文の形式や使用方法の詳細は、ルールSQLリファレンスをご参照ください。

ルールの作成

デプロイメントにアクセスし、左側ナビゲーションメニューのデータ統合をクリックしてデータ統合ページに入ります。初回アクセス時は必要に応じてデータ統合の種類を選択し、対応するアイコンをクリックしてターゲットサービスに接続するコネクターを作成します。コネクター作成の具体的な手順はコネクターの作成およびデータ統合の各種説明をご覧ください。

TIP

新しいコネクターをクリックするとデータ統合の初期ページに戻れます。

クラウドリソース接続用のコネクターを作成したら、ルール一覧の左上にある新しいルールをクリックして新しいルールページに入ります。コネクター一覧のルール作成ボタンからも新規ルールを作成可能です。

rules

メッセージ再パブリッシュ用のルールを作成する場合は、データ転送カテゴリの再パブリッシュをクリックしてルール作成を開始します。

rule_03

また、デバッグカテゴリの**何もしない（デバッグ）**をクリックしてルール作成を開始することも可能です。これはアクションを伴わない空のアクションを設定したルールで、ルールのデバッグに特化しています。詳細は空アクション（デバッグ）をご参照ください。

データソースの定義

新しいルールページでルール名を入力し、将来の管理のためにメモを追加します。

SQLエディターでは、ビジネスニーズに合ったデータソースを追加するためのSQL文をカスタマイズできます。ここでは以下のSQL文を入力してください：

sql

SELECT
  timestamp as up_timestamp, clientid as client_id, payload.temp as temp, payload.hum as hum
FROM
  "temp_hum/emqx"

このSQL文を指定することで、ルールはtemp_hum/emqxトピックにパブリッシュされたメッセージのペイロードに含まれるtimestamp、clientid、温度(temp)および湿度(hum)を読み取ります。

SQLジェネレーター

EMQX 5.91以降のDedicated Flexエディションでは、SQLエディターがAIによる自然言語からのルールSQL生成をサポートしています。この機能により、自然言語で意図を記述すると、システムが自動的に適切なSQL文を生成します。

利用手順は以下の通りです：

新しいルールページのSQLエディターセクションに移動します。
SQLジェネレーターボタンをクリックして、AIでSQLを生成ダイアログを開きます。
ダイアログで以下の項目を指定します：
- タスクの説明（必須）：SQLに何をさせたいかを自然言語で記述します。
  例：「MQTTメッセージのメタデータからclientidを抽出し、ペイロードからdevice_idとtemperatureを抽出する。トピックsensors/temperatureのメッセージで温度が30を超える場合のみ適用する。」
- 関連トピック（任意）：sensors/temperatureのようなトピックフィルターを指定します。
- 入力例（JSON）（任意だが推奨）：AIがデータ構造を理解しやすくするためのMQTTメッセージペイロードのサンプルを提供します。例：
  json
```
{
  "device_id": "sensor001",
  "temperature": 32.5,
  "unit": "C"
}
```
- 出力例（JSON）（任意）：期待する結果フォーマットを指定します。例：
  json
```
{
  "clientid": "client_a1b2c3",
  "device_id": "sensor001",
  "temperature": 32.5
}
```
  TIP
  入力例・出力例を含めることで生成されるSQLの精度が向上します。
生成をクリックして生成されたSQLをプレビューします。
プレビュー画面では：
- 生成されたSQLを確認・手動編集可能です。
- SQLを適用をクリックするとSQLエディターに挿入されます。
- 戻るをクリックして入力内容を修正し再生成も可能です。
SQLエディターに挿入すると、自動的にSQLエディターに表示され、確認・編集できます。

出力例

上記のタスクと入力例を使うと、生成されるSQLは以下のようになります：

sql

SELECT
  clientid,
  payload.device_id AS device_id,
  payload.temperature AS temperature
FROM
  "sensors/temperature"
WHERE
  payload.temperature > 30

このルールは、トピックsensors/temperatureのメッセージからclientid、device_id、temperatureフィールドを抽出し、温度が30を超える場合に適用されます。

SQLジェネレーターの利用シーン

SQLジェネレーターは以下の場合に特に有効です：

EMQXのSQL構文に不慣れな場合
ルールのプロトタイプを素早く作成したい場合
構造化されたJSONペイロードを扱う場合

より詳細なカスタマイズや構文オプションはルールSQL構文をご覧ください。

SQL文のテスト

Try It Outのトグルスイッチをオンにして新規のテストSQLを作成します。適切なテストパラメーターを入力し、テストボタンをクリックしてください。

出力結果に期待されるデータ処理結果が表示されます。

rule_enable_test

アクションの追加

ルールを作成後、ルールにアクションを追加できます。詳細はアクションをご覧ください。

ルールのテスト

注意

この機能はEMQX DedicatedおよびDedicated Flexエディションでのみ利用可能です。

ルールエンジンはルールテスト機能を提供しており、シミュレートデータや実際のクライアントデータを使ってルールをトリガーし、ルールSQLを実行し、ルールに追加されたすべてのアクションを実行し、各ステップの実行結果を取得できます。

ルールをテストすることで、ルールが期待通りに動作するか検証でき、問題の早期発見と解決が可能です。これにより開発スピードが向上し、実環境でのルールの正常稼働を保証し、運用時の障害を回避できます。

テスト手順

Try It Outスイッチをオンにし、テスト対象としてルールを選択します。テスト開始前にルールを保存しておく必要があります。
テスト開始ボタンをクリックしてテストを開始します。ブラウザは現在のルールがトリガーされるのを待ち、テスト結果を生成します。
ルールをトリガーしてテストします。以下の2つの方法が利用可能です：
- シミュレートデータを使用：シミュレートデータ入力ボタンをクリックし、ポップアップでSQLのFROM句に合致するデータソースを選択します。EMQXはすべてのフィールド（クライアントID、ユーザー名、トピック、QoS、ペイロードなど）にデフォルト値を提供します。必要に応じて修正し、テスト送信ボタンをクリックすると一度だけルールがトリガーされます。
- 実機データを使用：現在のページを開いたままにし、実際のクライアントやMQTTクライアントツールでEMQXに接続し、対応するイベントをトリガーしてテストします。
テスト結果の確認：ルールがトリガーされると、コンソールに実行結果が出力され、各ステップの詳細な実行結果が表示されます。

テスト例

MQTTXを使って再パブリッシュアクション付きのルールをテストできます。1つのクライアントを作成し、そのクライアントでa/1トピックをサブスクライブし、t/1メッセージを送信します。ダイアログボックスで、このメッセージがa/1トピックに再パブリッシュされるのが確認できます。

MQTTXクライアントツールとEMQXの接続構築方法の詳細はMQTTX - はじめにをご覧ください。

mqttx-test-rule

対応して、コンソールにはルール全体の実行結果が表示され、以下の内容が含まれます：

左側はルール実行記録です。ルールがトリガーされるたびに記録が生成され、クリックすると該当するメッセージやイベントの詳細に切り替えられます。
右側は選択したルールのアクション記録一覧です。クリックするとアクションの実行結果やログを展開して確認できます。

ルールSQLやいずれかのアクションの実行に失敗した場合、該当ルール記録全体が失敗としてマークされます。記録を選択すると対応するアクションのエラー情報を確認でき、トラブルシューティングに役立ちます。

test_rule

上記例から、ルールは4回トリガーされ、そのうち3回は完全に成功しています。4回目はHTTPサーバーアクションの実行失敗により失敗し、エラー理由はサービス利用不可でした。

ルール統計の確認

検証のためにtemp_hum/emqxトピックにメッセージを送信してください。

json

{
  "temp": "27.5",
  "hum": "41.8"
}

ルール一覧でルールIDをクリックすると、実行統計ページでルールの統計およびこのルールに属するすべてのアクションの統計を確認できます。ページ右上のリセットボタンをクリックするとメトリクスデータをリセットできます。

TIP

サーバレスデプロイメントではメトリクスリセットはサポートされていません。

rule_04

アクション統計の確認

出力アクション一覧でアクションIDをクリックすると、アクション統計ペインでこのアクションのメトリクスとレート指標を確認できます。右上のリセットボタンでメトリクスデータをリセット可能です。

TIP

現在、メトリクスの個別アクション表示はDedicatedおよびDedicated Flex版v5のデプロイメントのみ対応しています。

action_statistics

ルールの編集

ルール一覧で編集アイコンを直接クリックしてルールを編集するか、ルールIDをクリックして設定タブを選択して編集できます。設定ページではルールのSQLテンプレートを編集したり、アクションを編集・追加したりできます。

rule_05

ルールの有効化・無効化

ルール一覧で有効列のトグルスイッチをクリックしてルールを有効化または無効化できます。

ルールの削除

ルール一覧で削除ボタンをクリックし、ルールIDを入力してルールを削除できます。

アクションの有効化・無効化

注意

この機能はEMQX DedicatedおよびDedicated Flexエディションでのみ利用可能です。

アクション一覧で有効トグルスイッチをクリックするだけでアクションのオン・オフを切り替えられます。

アクションの編集・削除

アクションエリアでアクション名列の名前やアクション列の編集ボタンをクリックしてアクションを編集できます。削除ボタンをクリックするとアクションを削除できます。

専用フレックス

VPC ピアリング接続

PrivateLink の設定

拡張認証

拡張認可

ルール

LLM ベースの MQTT データ処理

サーバレスデプロイメント API

ルール ​

ルールの仕組み ​

ルールSQLの例 ​

ルールの作成 ​

データソースの定義 ​

SQLジェネレーター ​

出力例 ​

SQLジェネレーターの利用シーン ​

SQL文のテスト ​

アクションの追加 ​

ルールのテスト ​

テスト手順 ​

テスト例 ​

ルール統計の確認 ​

アクション統計の確認 ​

ルールの編集 ​

ルールの有効化・無効化 ​

ルールの削除 ​

アクションの有効化・無効化 ​

アクションの編集・削除 ​

ルール