EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

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

プラグインロジックのカスタマイズ ​

このページでは、src/my_emqx_plugin.erl にあるデフォルトテンプレートのロジックを変更して、EMQXプラグインをカスタマイズする方法を説明します。テンプレートはデフォルトで全ての利用可能なEMQXフックを登録しています。不要なフックは削除し、該当するコールバック内に独自のロジックを実装してください。

フック関数の登録 ​

例えば、認証および認可ロジックを追加するには、my_emqx_plugin:hook/0 関数を以下のように登録します。

erlang
hook() ->
  emqx_hooks:add('client.authenticate', {?MODULE, on_client_authenticate, []}, ?HP_HIGHEST),
  emqx_hooks:add('client.authorize', {?MODULE, on_client_authorize, []}, ?HP_HIGHEST).

ここで、on_client_authenticate/2 はクライアント認証を処理し、on_client_authorize/4 は認可を管理します。

1つのフック関数はEMQX本体とカスタマイズプラグインの両方でマウントされる可能性があるため、プラグインにマウントする際には実行順序を指定する必要があります。?HP_HIGHEST は現在のフック関数が最も優先度が高く、最初に実行されることを示します。

例：アクセス制御ロジックの追加 ​

以下は基本的なアクセス制御の実装例です。

erlang
%% クライアントIDがA-Z、a-z、0-9、アンダースコアのいずれかの文字で構成されている場合のみ接続を許可する。
on_client_authenticate(_ClientInfo = #{clientid := ClientId}, Result) ->
  case re:run(ClientId, "^[A-Za-z0-9_]+$", [{capture, none}]) of
    match -> {ok, Result};
    nomatch -> {stop, {error, banned}}
  end.

%% クライアントは /room/{clientid} 形式のトピックにのみサブスクライブ可能だが、任意のトピックにパブリッシュ可能。
on_client_authorize(_ClientInfo = #{clientid := ClientId}, subscribe, Topic, Result) ->
  case emqx_topic:match(Topic, <<"/room/", ClientId/binary>>) of
    true -> {ok, Result};
    false -> stop
  end;
on_client_authorize(_ClientInfo, _Pub, _Topic, Result) -> {ok, Result}.

このロジックにより以下が保証されます。

  • 有効なクライアントIDを持つクライアントのみ接続可能。
  • クライアントは任意のトピックにパブリッシュ可能。
  • クライアントは自身の /room/{clientid} トピックにのみサブスクライブ可能で、簡単なチャットルームの動作を実現。

TIP

  • EMQX設定で authorization.no_match = deny を設定すると、マッチしないアクセス試行をブロックできます。

  • ファイルベースの認可ルールについては、ファイルベース認可ドキュメントを参照してください。

設定スキーマの追加（任意） ​

EMQX 5.7.0以降、プラグインの設定はREST API経由で動的に管理可能です。この機能を有効にし、設定のバリデーションを行うには、プラグインに以下を含める必要があります。

  • 設定構造のバリデーション用に、相対パス priv/config_schema.avsc にAvroスキーマ設定ファイルを配置します。このファイルはApache Avro仕様に準拠している必要があります。
  • Avroスキーマルールに準拠したデフォルト設定ファイルを priv/config.hocon に配置します。

実行時には、更新された設定が data/plugins/<PLUGIN_NAME>/config.hocon に保存され、旧設定ファイルは自動的にバックアップされます。

TIP

プロジェクトディレクトリにある以下の例ファイルを参考にしてください。

  • priv/config.hocon.example
  • priv/config_schema.avsc.example
  • priv/config_schema.avsc.enterprise.example（UI宣言を含む）
  • priv/config_i18n.json.example（多言語対応用）

これらをテンプレートとして利用し、プラグインの設定スキーマやUIを構築できます。

宣言的UIの定義（任意） ​

Avroスキーマには $ui フィールドを含めることができ、EMQXダッシュボード上での設定項目の表示方法を定義できます。プラグイン利用者は動的に生成されたフォームを通じて設定を編集可能です。

また、priv/config_i18n.json に国際化（i18n）設定ファイルを用意できます。このファイルはキーと値のペアで構成され、例えば以下のようになります。

json
{
  "$msgid": {
    "zh": "消息",
    "en": "Message"
  }
}

フィールド名、説明、バリデーションルールのメッセージなどのUI要素で多言語対応を行うには、該当するUI設定内で $ プレフィックス付きの $msgid を使用してください。

設定項目の説明

宣言的UIコンポーネントはダッシュボード内での動的フォーム描画を可能にし、多様なフィールドタイプやカスタムコンポーネントに対応しています。以下に利用可能なコンポーネントとその設定内容を示します。

  • component
    必須。異なる値や型のデータを表示・設定するためのコンポーネントタイプを指定します。対応コンポーネントは以下の通りです。

    コンポーネント名説明
    input短いテキストや文字列用のテキスト入力ボックス
    input-password入力内容を隠すパスワード入力ボックス
    input-number数値のみを受け付ける数値入力ボックス
    input-textarea長文入力用のテキストエリア
    input-arrayカンマ区切りの配列入力ボックス。文字列配列・数値配列に対応
    switch真偽値用のトグルスイッチ
    select列挙型選択用のドロップダウンボックス
    code-editorSQLやJSONなど特定フォーマット用のコードエディター
    key-value-editorAvroマップ形式のキー・バリュー編集用エディター
    maps-editorAvroオブジェクト配列編集用エディター

  • label
    必須。フィールドのラベルまたは名称を定義し、国際化対応のために $msgid が利用可能です。i18n設定がない場合は原文がそのまま表示されます。

  • description
    任意。フィールドの詳細説明を記述し、こちらも $msgid による国際化が可能です。i18n設定がない場合は原文が表示されます。

  • flex
    必須。グリッドレイアウト内でのフィールドの幅を指定します。全幅は24、半幅は12です。

  • required
    任意。必須入力かどうかを示します。

  • format（code-editor コンポーネントのみ）
    任意。対応するデータフォーマットを指定します（例：sql、json）。

  • options（select コンポーネントのみ）
    任意。Avroスキーマのシンボルに対応した選択肢リストを指定します。例：

    json
    [
  {
    "label": "$mysql",
    "value": "MySQL"
  },
  {
    "label": "$pgsql",
    "value": "postgreSQL"
  }
]

  • items（maps-editor コンポーネントのみ）
    任意。maps-editorコンポーネント使用時に、フォーム内の項目名と説明を指定します。例：

    json
    {
  "items": {
    "optionName": {
      "label": "$optionNameLabel",
      "description": "$optionDesc",
      "type": "string"
    },
    "optionValue": {
      "label": "$optionValueLabel",
      "description": "$optionValueDesc",
      "type": "string"
    }
  }
}

  • rules
    任意。フィールドのバリデーションルールを定義します。複数ルールの設定が可能です。対応するタイプは以下の通りです。

    • pattern：正規表現による検証を行います。
    • range：数値の範囲検証を行います。最小値（min）と最大値（max）を両方または片方だけ設定可能です。
    • length：文字数の範囲検証を行います。最小長（minLength）と最大長（maxLength）を両方または片方だけ設定可能です。
    • message：検証失敗時に表示するエラーメッセージを指定します。多言語対応のため $msgid が利用可能です。

バリデーションルールの例：

以下は一部の例スニペットです。詳細は priv/config_schema.avsc.example を参照してください。

json
{
    "rules": [
    {
      "type": "pattern",
      "pattern": "^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])(\\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9]))*$",
      "message": "$hostname_validate"
    }
  ]
}
json
{
    "rules": [
    {
      "type": "range",
      "min": 1,
      "max": 65535,
      "message": "$port_range_validate"
    }
  ]
}
json
{
    "rules": [
    {
      "type": "length",
      "minLength": 8,
      "maxLength": 128,
      "message": "$password_length_validate"
    },
    {
      "type": "pattern",
      "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[a-zA-Z\\d]*$",
      "message": "$password_validate"
    }
  ]
}

プラグインパッケージにAvroスキーマやi18nファイルを含めることで、プラグインのコンパイルやパッケージング時に組み込まれます。プラグインコード内では emqx_plugins:get_config/1,2,3,4 関数を使って設定値を取得できます。