EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

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

ネームスペースの設定と管理 ​

ネームスペースは、ダッシュボードおよびREST APIを使用して設定および管理できます。セッション制限、レート制限の設定や、接続中のクライアントの管理が可能です。

ネームスペースのレート制限 ​

ネームスペースの設定は主に最大セッション数制限とレートリミッターの設定を含みます。レートリミッターを設定する前に、ネームスペースに利用可能なレートリミッターの種類とその適用範囲を理解することを推奨します。

具体的な設定方法については、ダッシュボードによるネームスペースの設定と管理を参照してください。

ネームスペースのレートリミッターは、特定のネームスペース内のクライアントに対するメッセージトラフィックや帯域幅の使用を制御するために使用できます。設定するレートリミッターの種類に応じて、既存のEMQXのレート制御機構（ゾーンレベルやリスナーレベルのレートリミッターなど）と連携して動作します。

レートリミッターの種類 ​

管理対象のネームスペースに対して利用可能なレートリミッターは2種類あります。

テナントレートリミッター ​

テナントレートリミッターは、同じネームスペース内のすべてのクライアントで共有されるトークンを割り当てます。

このリミッターが有効な場合：

  • 制限はネームスペース全体に適用されます
  • 既存のゾーンレベルのレートリミッターと連携して動作します
  • クライアントはゾーンレベルおよびネームスペースレベルの両方の制限を満たす必要があります

このタイプは、テナント全体のトラフィックを制御したいシナリオに適しています。

クライアントレートリミッター ​

クライアントレートリミッターは、ネームスペース内の各クライアントに専用のトークンを割り当てます。

このリミッターが有効な場合：

  • 制限は個々のクライアントに適用されます
  • リスナーレベルのレートリミッターを上書きします
  • リスナーレベルのレート制限は無視され、ネームスペースのクライアントレートリミッターのみが適用されます

このタイプは、個々のクライアントの挙動を細かく制御したいシナリオに適しています。

対応する制限の次元 ​

テナントおよびクライアントレートリミッターは、以下の次元をサポートしています。

  • メッセージレート制限：クライアントまたはテナントが指定期間内にパブリッシュできる最大メッセージ数
  • バイトスループット制限：指定期間内に送信可能な有効ペイロードサイズの最大値

:::

レート制御の詳細については、レート制限を参照してください。

:::

ダッシュボードによるネームスペースの設定と管理 ​

ダッシュボードの左側メニューから Management -> Namespace に移動します。Namespace ページでは、ネームスペースの一覧表示、編集、削除、および各ネームスペースに接続しているクライアントの管理が可能です。

デフォルトでは、ネームスペース一覧には明示的に作成されたネームスペースのみが表示されます。ページ左上のスイッチを切り替えることで、明示的に作成されたネームスペースと、client_attrs.tns 属性からEMQXが自動生成したネームスペースの両方を表示できます。

注意

自動生成されたネームスペースはダッシュボード上で編集できません。

ダッシュボードでのネームスペース設定 ​

ネームスペースは作成時に設定することも、後から編集することも可能です。既存のネームスペースを編集するには、そのネームスペースの Actions 列にある Edit をクリックします。

  1. Create Namespace ダイアログで以下の設定を行います。

    • Max Sessions：デフォルトは infinity（無制限）です。有効にすると、最大セッション数を指定して、単一ネームスペース内で過剰なクライアントによるリソース占有を防止できます。最大セッション数を設定する際は、クラスターのキャパシティに合わせて設定し、低すぎる制限による接続拒否を避けてください。

    • Tenant Limiter：ネームスペース内のすべてのクライアントのトラフィックを制御します。例えば、複数クライアントが同じインフラを共有する場合、テナントレート制限により帯域幅の公平な分配が可能です。デフォルトでは無効です。有効にすると以下のレート制限を設定できます。

      TIP

      この設定の詳細はダッシュボードのツールチップを参照してください。

      • Packet Publish Rate：現在のテナントがEMQXに送信できるバイト数の秒あたり制限
      • Packet Publish Burst：バースト時に追加で送信可能なバイト数
      • Messages Publish Rate：テナントが秒あたりに送信可能な最大メッセージ数
      • Messages Publish Burst：バースト時に追加で送信可能なメッセージ数

    • Client Limiter：個々のクライアントのトラフィックを制御します。クライアントレートリミッターはクライアントごとに独立しており、一つのクライアントの制限が他のクライアントに影響を与えません。デフォルトでは無効です。有効にすると以下のレート制限を設定できます。

      TIP

      この設定の詳細はダッシュボードのツールチップを参照してください。

      • Packet Publish Rate：クライアントがEMQXに送信できるバイト数の秒あたり制限
      • Packet Publish Burst：バースト時に追加で送信可能なバイト数
      • Messages Publish Rate：クライアントが秒あたりに送信可能な最大メッセージ数
      • Messages Publish Burst：バースト時に追加で送信可能なメッセージ数

  2. 設定が完了したら Create をクリックします。新しいネームスペースが一覧に表示されます。

ダッシュボードでのネームスペース削除 ​

ネームスペースを削除するには、Actions 列の Delete をクリックし、確認後にネームスペースが完全に削除されます。

注意

ネームスペースを削除する前に、そのネームスペースに関連付けられたすべてのアクティブなクライアントが適切に切断されていることを確認してください。

特定のネームスペースに接続しているクライアントを表示するには、Actions 列の Clients をクリックします。クライアントの一括切断も可能です。

REST APIによるネームスペースの設定と管理 ​

TIP

詳細かつ最新のリクエストおよびレスポンスのエンドポイントスキーマについては、対応するSwagger APIドキュメントを必ずご確認ください。これらはダッシュボードのリスナーで /api-docs にて提供されています。

REST APIでのネームスペース一覧取得 ​

EMQXは、必要に応じてネームスペースの詳細を一覧表示するための2つのエンドポイントを提供しています。

エンドポイント対象範囲設定情報含むか
GET /mt/ns_list_detailsすべてのネームスペース（自動生成および明示的作成）含まない
GET /mt/managed_ns_list_details明示的に作成された（管理対象の）ネームスペースのみ含む

両エンドポイントは同じクエリパラメータをサポートします。

パラメータ型デフォルト説明
last_nsString""ページネーション用カーソル。前ページの最後のアイテムの name を渡して次ページを取得します。
limitInteger1001ページあたりの最大ネームスペース数。

すべてのネームスペース一覧取得 ​

GET /mt/ns_list_details は、クライアント接続メタデータから自動生成されたネームスペースも含むすべてのネームスペースを返します。各アイテムには name と created_at のみが含まれ、設定情報は含まれません。

レスポンス例

json
[
  { "name": "ns1", "created_at": 1747917753 },
  { "name": "ns2", "created_at": 1747917754 }
]

管理対象ネームスペースの設定付き一覧取得 ​

GET /mt/managed_ns_list_details は、明示的に作成されたネームスペースのみを返し、各ネームスペースの現在の設定をインラインで含みます。管理UIはこのエンドポイントを使い、一度のリクエストで設定情報付きの完全な一覧を表示できます。

レスポンス例

json
[
  {
    "name": "ns1",
    "created_at": 1747917753,
    "config": {
      "session": {
        "max_sessions": 100
      },
      "limiter": {
        "tenant": {
          "bytes": { "rate": "20MB/10s", "burst": "300MB/1m" },
          "messages": { "rate": "5000/1s", "burst": "60/1m" }
        },
        "client": {
          "bytes": { "rate": "10MB/10s", "burst": "200MB/1m" },
          "messages": { "rate": "3000/1s", "burst": "40/1m" }
        }
      }
    }
  },
  {
    "name": "ns2",
    "created_at": 1747917754,
    "config": {}
  }
]

各アイテムには以下が含まれます：

  • name：ネームスペースの識別子
  • created_at：ネームスペース作成時のUnixタイムスタンプ（秒）
  • config：ネームスペースの設定。空オブジェクト {} は設定が適用されていないことを示します。設定フィールドの詳細はREST APIによるネームスペース設定を参照してください。

特定のネームスペースの完全な設定を取得するには、GET /mt/ns/<namespace>/config を使用します。

REST APIによるネームスペース設定 ​

ネームスペース作成後、PUT /mt/ns/<namespace>/config APIを使って設定を行えます。

このエンドポイントでレート制限、セッション制限、その他ネームスペース固有の設定を行います。

設定例 ​

以下はREST APIでネームスペースを設定する例です。ns1 ネームスペース内のクライアントに対して特定のレート制限を設定し、同時に最大セッション数も制限します。

ネームスペースの作成 ​

設定を適用する前に、ネームスペースが明示的に作成されていることを確認してください。

bash
# リクエストボディは不要です
POST /mt/ns/ns1

重要

クライアントがネームスペースを明示的に作成する前に接続した場合、後から適用されるレートリミッターなどの設定は継承されません。新しい設定を強制するには、それらのクライアントを手動で切断し再接続させる必要があります。

レート制限およびセッション制限の設定 ​

ネームスペース作成後、以下のように設定を適用します。

PUT /mt/ns/ns1/config

リクエストボディ例

json
{
  "limiter": {
    "client": {
      "bytes": {
        "rate": "10MB/10s",
        "burst": "200MB/1m"
      },
      "messages": {
        "rate": "3000/1s",
        "burst": "40/30s"
      }
    },
    "tenant": {
      "bytes": {
        "rate": "20MB/10s",
        "burst": "300MB/1m"
      },
      "messages": {
        "rate": "5000/1s",
        "burst": "60/30s"
      }
    }
  },
  "session": {
    "max_sessions": 100
  }
}

この設定は、クライアント固有およびテナント全体のレート制限を適用し、ネームスペースの最大セッション数を100に制限します。

ネームスペースのレートリミッター無効化 ​

レート制限を完全に解除したい場合は、再度設定を更新し、リミッタータイプを "disabled" に設定します。

PUT /mt/ns/ns1/config

リクエストボディ例

json
{
  "limiter": {
    "client": "disabled",
    "tenant": "disabled"
  }
}

REST APIによるネームスペース削除 ​

ネームスペースとその関連設定を削除するには、DELETE /mt/ns/<namespace> APIを使用します。

注意

ネームスペースを削除する前に、そのネームスペースに関連付けられたすべてのアクティブなクライアントが適切に切断されていることを確認してください。EMQXはネームスペース配下のすべてのセッションを一括キックするAPIを提供しており、管理対象ネームスペース削除時にはこの処理が自動的に実行されます。