EMQX Cloud

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

システムトピックとクライアントイベントのサブスクライブ ​

EMQX は、クライアントの接続、切断、サブスクライブイベントを、$SYS/ プレフィックス付きのシステムトピックにパブリッシュします。例えば以下のようなトピックです。

$SYS/brokers/${node}/clients/${clientid}/connected

$SYS システムトピックはブローカーノードレベルの情報を含み、内部のブローカーの可観測性、互換性、および運用診断を目的としています。EMQX Cloud でシステムトピックをサブスクライブするには、デフォルトの ACL ルールに適切な認可を追加する必要があります。例えば、emqx のようなユーザー名に対して $SYS/# のサブスクライブを許可します。

本番のビジネス統合では、クライアントイベントをキャプチャするために EMQX Cloud のデータ統合を使用し、Republish アクションでビジネストピックに転送する方法が推奨されます。EMQX Cloud は、ルール SQL によるイベントデータのフィルタリングや変換をサポートし、その結果を任意の MQTT トピックにパブリッシュできます。

本ページでは、EMQX Cloud におけるシステムトピックの仕組みと、データ統合を使ってクライアントイベントをビジネストピックに転送し、下流で利用する方法を説明します。

それぞれのアプローチを使うタイミング ​

システムトピックはブローカーの可観測性、互換性アダプター、運用診断に適しています。クライアントの接続・切断・サブスクライブイベントをキャプチャし、本番システムに統合することが目的であれば、データ統合の利用がより適切です。

項目$SYS システムトピックデータ統合 + Republish
ユースケースブローカーの可観測性、診断、互換性ビジネス統合、イベント転送
トピック構造${node} を含み、内部ブローカーノード名に紐づく安定したカスタムビジネストピックに Republish
データ処理クライアント側で生メッセージを解析ルール SQL で中央集約的にフィルタリング・変換・マスク
セキュリティ境界内部ブローカーノード情報を露出する可能性があるビジネストピックに独立したアクセス制御を設定可能
拡張性サブスクライブのみの観測MQTT トピックや外部システムへ同時転送可能

システムトピック ​

システムトピックは $SYS/brokers/${node}/... の形式で、${node} はブローカーノード名（例: emqx@127.0.0.1）です。

クライアントイベントトピック ​

クライアントの状態イベントに利用可能なシステムトピックは以下の通りです。

イベントシステムトピック
クライアント接続$SYS/brokers/${node}/clients/${clientid}/connected
クライアント切断$SYS/brokers/${node}/clients/${clientid}/disconnected
クライアントサブスクライブ$SYS/brokers/${node}/clients/${clientid}/subscribed
クライアントサブスクライブ解除$SYS/brokers/${node}/clients/${clientid}/unsubscribed

注意

上記4種類のイベントはデフォルトで有効です。これらをサブスクライブするには、デフォルト ACL ルールに適切な認可を追加してください。例えば、特定のユーザー名に対して $SYS/# のサブスクライブを許可します。

データ統合でクライアントイベントをキャプチャする（推奨） ​

データ統合は $events/ プレフィックス付きの組み込みイベントトピックを提供します。これらはシステムトピックより安定しており、ノード名に依存せず、ルール SQL によるデータ処理をサポートしています。デフォルトではクライアントがこれらのイベントトピックを直接サブスクライブすることはできず、データ統合ルールで処理・転送する必要があります。各イベントの利用可能なフィールドの詳細は、SQL データソースとフィールド — MQTT イベント を参照してください。

システムトピックとデータ統合イベントトピックの比較 ​

イベント$SYS システムトピックデータ統合イベントトピック
クライアント接続$SYS/brokers/${node}/clients/${clientid}/connected$events/client/connected
クライアント切断$SYS/brokers/${node}/clients/${clientid}/disconnected$events/client/disconnected
クライアントサブスクライブ$SYS/brokers/${node}/clients/${clientid}/subscribed$events/session/subscribed
クライアントサブスクライブ解除$SYS/brokers/${node}/clients/${clientid}/unsubscribed$events/session/unsubscribed

注意

新規ルールでは、$events/client/connected や $events/session/subscribed のような名前空間付きイベントトピックを使用してください。従来のイベントトピック形式も引き続きサポートされていますが、新規設定では推奨されません。

推奨アーキテクチャ ​

イベントをデータ統合ルール経由でビジネストピックに転送し、ビジネスクライアントは直接システムトピックに依存せずにビジネストピックをサブスクライブする構成です。

$events/client/#  または  $events/session/#
  → データ統合ルールの SQL（フィルタリング、変換）
  → Republish アクション
  → ビジネストピック（例: iot/events/client/connected）
  → ビジネスクライアントがサブスクライブ

クライアントイベント転送用のデータ統合設定例 ​

以下は4種類のクライアントイベントそれぞれに対するルールと Republish アクションの設定例です。

クライアント接続 ​

イベントトピック

$events/client/connected

ルール SQL

sql
SELECT
  clientid,
  username,
  peername,
  proto_name,
  proto_ver,
  keepalive,
  clean_start,
  expiry_interval,
  connected_at,
  timestamp,
  node
FROM
  "$events/client/connected"

推奨 Republish トピック

iot/events/client/connected

ペイロードテンプレート

json
{
  "event": "client.connected",
  "clientid": "${clientid}",
  "username": "${username}",
  "peername": "${peername}",
  "proto_name": "${proto_name}",
  "proto_ver": ${proto_ver},
  "keepalive": ${keepalive},
  "clean_start": ${clean_start},
  "expiry_interval": ${expiry_interval},
  "connected_at": ${connected_at},
  "timestamp": ${timestamp},
  "node": "${node}"
}

クライアント切断 ​

イベントトピック

$events/client/disconnected

ルール SQL

sql
SELECT
  clientid,
  username,
  reason,
  peername,
  connected_at,
  disconnected_at,
  timestamp,
  node
FROM
  "$events/client/disconnected"

推奨 Republish トピック

iot/events/client/disconnected

ペイロードテンプレート

json
{
  "event": "client.disconnected",
  "clientid": "${clientid}",
  "username": "${username}",
  "reason": "${reason}",
  "peername": "${peername}",
  "connected_at": ${connected_at},
  "disconnected_at": ${disconnected_at},
  "timestamp": ${timestamp},
  "node": "${node}"
}

クライアントサブスクライブ ​

イベントトピック

$events/session/subscribed

ルール SQL

sql
SELECT
  clientid,
  username,
  topic,
  qos,
  sub_props,
  timestamp,
  node
FROM
  "$events/session/subscribed"

推奨 Republish トピック

iot/events/session/subscribed

ペイロードテンプレート

json
{
  "event": "session.subscribed",
  "clientid": "${clientid}",
  "username": "${username}",
  "topic": "${topic}",
  "qos": ${qos},
  "sub_props": ${sub_props},
  "timestamp": ${timestamp},
  "node": "${node}"
}

クライアントサブスクライブ解除 ​

イベントトピック

$events/session/unsubscribed

ルール SQL

sql
SELECT
  clientid,
  username,
  topic,
  qos,
  unsub_props,
  timestamp,
  node
FROM
  "$events/session/unsubscribed"

推奨 Republish トピック

iot/events/session/unsubscribed

ペイロードテンプレート

json
{
  "event": "session.unsubscribed",
  "clientid": "${clientid}",
  "username": "${username}",
  "topic": "${topic}",
  "qos": ${qos},
  "unsub_props": ${unsub_props},
  "timestamp": ${timestamp},
  "node": "${node}"
}

データ統合ルールの作成 ​

EMQX Cloud コンソールで以下の手順に従い、ルールを作成し Republish アクションを追加します。

  1. デプロイメントの データ統合 ページに移動します。
  2. データ転送 の下で Republish を選択し、作成 をクリックします。
  3. SQL エディタにルール SQL を入力します。
  4. 次へ をクリックし、Republish アクションを追加します。
  5. 転送先のビジネストピック、ペイロードテンプレート、QoS、リテインフラグなどのパラメータを設定します。
  6. 確定 をクリックして保存し、SQL テストツールでルールの動作を検証します。

TIP

Republish したメッセージが同じルールを再度トリガーしないようにするには、アクション設定で Direct Dispatch を有効にしてください。Direct Dispatch を有効にすると、メッセージはルールエンジンを経由せず直接サブスクライバーに配信され、ループトリガーを防止できます。

ベストプラクティス ​

  • クライアントの接続、切断、サブスクライブ、サブスクライブ解除イベントの統一ソースとして $events/client/# および $events/session/# を使用してください。
  • データ統合ルールの SQL でイベントデータを中央集約的にフィルタリング、変換、マスクしてください。
  • イベントは iot/events/client/+ や iot/events/session/+ のような安定したビジネストピックに Republish し、ビジネスシステムが $SYS/brokers/${node}/... の内部トピック構造に依存しないようにします。
  • ビジネスクライアントはビジネストピックのみをサブスクライブし、それらのトピックに対して独立した ACL ルールを適用してアクセス制御と分離を強化してください。
  • 監査、クエリ、モニタリング、アラートのために必要に応じてイベントを外部システムに書き出してください。