ジョブとプラグイン: MQTTトピックの権限

対象: ジョブタスクまたは管理対象プラグイン向けにMQTTトピックの権限を構成する統合担当者向けです。

本ページは、MQTTブローカーが統合担当者が作成したコンポーネントに対してトピック権限をどのように適用するかをまとめたリファレンスです。MQTTがより広い統合フローのどこに位置するかの説明については、カスタムジョブ統合ガイドの手順3およびカスタムプラグイン統合ガイドの手順2をご参照ください。

適用の仕組み

トピック権限はコンポーネントのJSONファイルで宣言され、実行時にブローカーによって適用されます。適用モデルは以下の4段階です。

宣言: ジョブはジョブルートオブジェクトの mqttTopics に許可トピックを宣言します。プラグインはプラグインJSONの metadata.mqttTopics に宣言します。

接続: コンポーネントがブローカーへ接続すると、ブローカーは起動済みプロセスのレジストリに対してクライアントを検証し、クライアントIDの形式から当該接続がどのジョブまたはプラグインに属するかを特定します。

適用: すべてのpublishとsubscribeが、そのコンポーネントの宣言済み許可リストに対してチェックされます。宣言されていないトピックへの呼び出しは拒否されます。MQTT接続自体は切断されず、個々の操作だけが失敗します。

サイレントな拒否: 拒否されたpublishまたはsubscribeは、多くの場合クライアントから見えるエラーになりません。接続レベルでは成功しているように見えるのにメッセージが届かない場合は、まずトピック宣言の漏れを確認してください。

ジョブ

ジョブタスクのトピック権限は、タスク定義の内側ではなく、ジョブルートオブジェクトに宣言します。

"mqttTopics": {
  "allowedPublications": ["KeeperLogger"],
  "allowedSubscriptions": []
}

フィールド

目的

allowedPublications

タスクがpublishしてよいトピックです。バイナリがpublishするすべてのトピックを含める必要があります (KeeperLogger、eventTopic、カスタムトピックなど)。

allowedSubscriptions

タスクが subscribe してよいトピックです。ログのみpublishするジョブタスクでは多くの場合空です。

mqttTopics が少なくとも1エントリ付きで存在する場合、エージェントはタスク開始前に KEEPER_JOB_ID と KEEPER_JOB_NAME を環境変数として注入します。正しいMQTTクライアントIDの構成に必要です。

タスクがMQTTをまったく使わない場合は、mqttTopics ごと省略できます。その場合、KEEPER_JOB_ID と KEEPER_JOB_NAME は注入されません。

プラグイン

管理対象プラグインのトピック権限は、プラグインJSONの metadata 配下に宣言します。

"metadata": {
  "mqttTopics": {
    "publish": ["KeeperLogger", "MyPlugin/Responses/+"],
    "subscribe": ["MyPlugin/Commands/+"]
  }
}

フィールド

目的

publish

プラグインがpublishしてよいトピックです。

subscribe

主たる Subscription.Topic に加えて subscribe してよいトピックです。

主たる Subscription.Topic は metadata.mqttTopics.subscribe とは別フィールドです。両方とも subscribe の対象になります。主たる購読に加える追加トピックは metadata.mqttTopics.subscribe に宣言し、置き換えではなく併記してください。

並べて比較

ジョブ (Jobs/*.json)

プラグイン (Plugins/*.json)

宣言の場所

ジョブルートの mqttTopics

プラグインJSON内の metadata.mqttTopics

Publishのフィールド名

allowedPublications

publish

Subscribeのフィールド名

allowedSubscriptions

subscribe

主たる購読

該当なし

Subscription.Topic として別途宣言

MQTTクライアントIDの形式

{KEEPER_JOB_ID}_{Token}_{Pid}

{PluginName}_{Pid} または {PluginName}_{UserName}_{Pid}

環境変数

mqttTopics 設定時に KEEPER_JOB_ID、KEEPER_JOB_NAME を注入

環境変数では注入しない。プラグインは自身の id から識別を読み取る

MQTTクライアントID

ブローカーはクライアントIDの形式によって接続をジョブまたはプラグインに関連付け、正しい権限セットを適用します。形式が誤っていると、トピック宣言が正しくても権限チェックに失敗します。

ジョブタスク向け:

{KEEPER_JOB_ID}_{ExecutableToken}_{ProcessId}

KEEPER_JOB_ID は、エージェントが注入する環境変数から取得します
ExecutableToken は、バイナリの短い安定識別名です。アンダースコアやパス文字は含めません
ProcessId は、現在のOSプロセスIDの10進表記です
ジョブの id にはアンダースコアを含めません。ブローカーは _ で分割してジョブID部分を取り出します

例: my-scanner_SecretScanner_48292

管理対象プラグイン向け:

{PluginName}_{ProcessId}                      (サービスアカウント)
{PluginName}_{UserName}_{ProcessId}           (ユーザーセッション)

PluginName は、プラグインの id と一致させます
プラグインではジョブの3要素形式のクライアントIDを使わないでください。形式に応じてブローカー側で異なる権限ロジックが適用されます

ワイルドカード

パターン

範囲

用途

+

ちょうど1レベルのトピックに一致

種別ごとにサブトピックが変わるコマンド/応答パターン。例: Commands/+ は Commands/scan と Commands/reset に一致するが Commands/a/b には一致しない

#

プレフィックス以下のすべてのレベルに一致

広い監視やログパターン。必要な場合に限り慎重に利用

本番では明示的なトピック文字列を優先してください。ワイルドカードは開発時には便利ですが、ブローカーが強制できる範囲は狭くなります。コマンド集合が限定的なら、トピックを列挙するのがよいでしょう。

"publish": [
  "KeeperLogger",
  "MyPlugin/Responses/scan",
  "MyPlugin/Responses/reset"
]

KeeperLogger

KeeperLogger は構造化ログ配信用の既知のトピックです。構造化ログメッセージをpublishするジョブタスクまたはプラグインは、publishリストにこれを含める必要があります。ペイロードは RequestMessage のJSON形式に従う必要があります。形式の詳細とコード例はカスタムジョブ統合ガイドをご参照ください。

管理者がコンポーネント向けに明示的に権限を拡張していない限り、製品内部のトピック (ポリシー、API など) にはpublishしないでください。

よくある失敗

症状

原因

対処

Publishがサイレントに失敗する

トピックが allowedPublications / publish にない

正しい宣言リストにトピックを追加する

Subscribe がサイレントに失敗する

トピックが allowedSubscriptions / subscribe にない

正しい宣言リストにトピックを追加する

eventTopic のpublishが拒否される

eventTopic 文字列が allowedPublications に含まれていない

正確に一致する eventTopic 文字列を allowedPublications に追加する (文字列は完全一致が必要)

宣言は正しいのに権限チェックが失敗する

クライアントIDの形式が誤っている (ジョブ用形式をプラグインに使うなど)

コンポーネント種別に合ったクライアントID形式か確認する

MQTT接続そのものが拒否される

プロセスが起動済みプロセスのレジストリにない

手動ではなくエージェント (ジョブランナーまたはオーケストレーター) がバイナリを起動しているか確認する。起動時の再試行を追加する

前へジョブ: KeeperAdminCLI実行ガイド次へプラグインとジョブの登録

最終更新 5 日前