EMQX Platform

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ

ルール ​

ルール（ルールエンジンとも呼ばれます）は、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版では、SQLエディターがAIによる自然言語からのルールSQL生成をサポートしています。この機能により、自然言語で意図を記述すると、システムが自動的に適切なSQL文を生成します。

利用手順：

  1. 新しいルールページのSQLエディターセクションに移動します。

  2. SQLジェネレーターボタンをクリックして、AIでSQL生成ダイアログを開きます。

    sql_editor

    ダイアログ内で以下の項目を指定します：

    • タスク説明（必須）：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の精度が向上します。

  3. 生成をクリックして生成されたSQLをプレビューします。

  4. プレビュー画面では以下が可能です：

    • 生成されたSQLの確認および手動編集
    • SQLを適用をクリックしてSQLエディターに挿入
    • 戻るをクリックして入力を修正し再生成

  5. 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文のテスト ​

テストを有効にするトグルスイッチをクリックして新規テストSQLを作成します。適切なテストパラメータを入力し、テストボタンを押します。

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

rule_enable_test

アクションの追加 ​

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

ルールのテスト ​

注意

この機能はEMQX Dedicated版でのみ利用可能です。

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

ルールをテストすることで、期待通りに動作するか検証でき、問題の早期発見と解決が可能です。これにより開発効率が向上し、本番環境での失敗を防止できます。

テスト手順 ​

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

テスト例 ​

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をクリックすると、ルールの統計情報およびこのルール配下のすべてのアクションの統計を実行統計ページで確認できます。

rule_04

アクション統計の確認 ​

アクション一覧でアクションIDをクリックすると、アクション統計ページに移動し、このアクションのメトリクスやレート指標を閲覧できます。

TIP

現在、個別アクションのメトリクス閲覧はDedicated版v5のデプロイメントのみサポートされています。

action_statistics

ルールの編集 ​

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

rule_05

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

ルール一覧で有効列のトグルスイッチをクリックして、ルールの有効化・無効化を切り替えられます。

ルールの削除 ​

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

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

注意

この機能はEMQX Dedicated版でのみ利用可能です。

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

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

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