プラグインとジョブの登録

対象: プラグインとジョブの検出、登録、読み込みの仕組みを把握する必要があるIT管理者。

プラグインの登録

プラグインの登録方法

プラグインは Plugins/ ディレクトリ内のJSONファイルから検出されます。エージェントは起動時にこれらのファイルを読み取り、検証し、startupPriority と autoStart の設定に従ってプラグインを起動します。pluginType: Executable のプラグインは別プロセスとして実行され、pluginType: Service のものはメインエージェントプロセス内で動作します。

場所: {approot}/Plugins/ (例: C:\Program Files\KeeperPrivilegeManager\Plugins)
ファイル名: {PluginName}.json (例: KeeperPolicy.json)

新しいプラグインを追加するには、プラグインのバイナリを Plugins/bin/{PluginName}/ に置き、Plugins/{PluginName}.json にプラグインJSONファイルを追加します。サービス再起動後 (または対応している場合はプラグインの再読み込み後)、新しいプラグインが登録され、起動できるようになります。

プラグインJSONフィールド

プラグインJSONファイルには以下のフィールドが含まれます。プラグインによってはすべてが必要ではありません。ご利用のエージェントバージョンについては、カスタムプラグイン統合ガイドおよび管理者向けドキュメントでご確認ください。

フィールド

説明

id

一意のプラグイン識別子。/api/PluginSettings/{id} で使うファイル名およびキーとの一致が必要

pluginType

別プロセスの場合は Executable。プロセス内コンポーネントの場合は Service

executablePath

プラグインバイナリへのパス。エージェントルートからの相対パスまたは絶対パス。プロセス内プラグインでは省略

supportedPlatforms

OS名の配列。非対応プラットフォームではエージェントがプラグインをスキップ

Subscription

主MQTTサブスクリプション: Topic、Qos、CleanSession

metadata.mqttTopics

主サブスクリプションに加える追加の subscribe および publish トピック権限

startupPriority

起動順序の制御。数値が小さいほど先に起動

autoStart

true のとき、起動時にプラグインを起動

executionContext

プラグインプロセスの実行コンテキスト: Service、User、Interactive

requiresMonitoring

true のとき、プロセス監視による予期しない終了の検出

autoRestart

true のとき、監視で停止を検出した場合のプラグイン再起動

プラグインJSONの例:

{
  "id": "KeeperPolicy",
  "name": "Keeper Policy Service",
  "pluginType": "Executable",
  "executablePath": "{pluginroot}/KeeperPolicy/bin/Release/net8.0/KeeperPolicy",
  "supportedPlatforms": ["Windows", "Linux", "macOS"],
  "Subscription": {
    "Topic": "KeeperPolicy",
    "Qos": 2,
    "CleanSession": true
  },
  "startupPriority": 20,
  "autoStart": true,
  "executionContext": "Service"
}

プラグインのライフサイクル

起動: エージェントがプラグイン実行ファイルを起動するか、プロセス内コンポーネントを読み込みます。プラグインはMQTTにサブスクライブし、処理を開始します。
停止/再起動: 管理者はローカル管理API経由でプラグインを停止または再起動できます (例: POST /api/plugins/{name}/stop または /restart)。autoRestart: true が設定されている場合、予期しない終了時にエージェントがプラグインを自動再起動します。
設定: プラグイン設定は統合ストレージまたはプラグインJSONに保存できます。ポリシーまたはAPIで配信された更新は、反映にプラグインの再起動が必要な場合があります。

MQTTサブスクリプションとパブリッシュ権限

プラグインはプラグインJSONでMQTTアクセスを宣言します。エージェントは起動時にこれらの宣言を読み込み、サブスクライブおよびパブリッシュ可能なトピックの制御に用います。

主サブスクリプション: すべてのプラグインは Subscription ブロックで主MQTTトピックを1つ宣言する必要があります。リクエストおよび制御メッセージ向けの主な受信トピックです。

"Subscription": {
  "Topic": "KeeperPolicy",
  "Qos": 2,
  "CleanSession": true
}

追加トピック権限: プラグインは metadata.mqttTopics で追加のサブスクライブおよびパブリッシュ権限を宣言できます。

"metadata": {
  "mqttTopics": {
    "subscribe": ["AuditMessage", "EventMessages"],
    "publish": ["KeeperLogger", "EventMessages"]
  }
}

エージェントは主サブスクリプショントピックと追加サブスクライブトピックを組み合わせて、プラグインの実効的なサブスクリプション集合を構成します。トピック検証はブローカーで適用され、登録で許可されたトピックに限りサブスクライブまたはパブリッシュできます。subscribe および publish 配列では、必要に応じてMQTTワイルドカード (+ および #) を使えます。

ジョブの登録

ジョブの登録方法

ジョブは Jobs/ ディレクトリ内のJSONファイルから検出されます。ジョブランナーは起動時およびファイル変更時にこのディレクトリをスキャンし、各JSONファイルを解析・検証してジョブを登録します。有効なジョブはスケジュールおよびイベントトリガーで利用可能になります。無効なファイルはスキップされ、エラーがログに記録されます。

場所: {approot}/Jobs/ (例: C:\Program Files\KeeperPrivilegeManager\Jobs)
ファイル名: {job-id}.json。ファイル内の id フィールドは .json 拡張子を除いたファイル名と一致する必要があります

ジョブにおける「登録」の意味

登録済みジョブは読み込まれ、構造が有効で、ジョブランナーに認識されています。enabled が true で、宣言された condition を満たしていれば、トリガーが発生したときに実行されます。

未登録ジョブは、ファイルが存在しない、解析不能、または未読み込みの状態です。トリガーに関係なく実行されません。

ジョブを別手順で登録する必要はありません。有効な {id}.json を Jobs/ ディレクトリに置くだけで十分です。次回の再スキャンまたは再起動でジョブランナーが取り込みます。ジョブはHTTP API (POST /api/Jobs、PUT /api/Jobs/{id}) から作成・更新することもでき、JSONの書き込みとラストノウングッドストアの更新が一度に行われます。ラストノウングッドが有効な場合は、ファイルを直接置くより API または JobUpdate ポリシーを優先してください。手編集したファイルは元に戻る場合があります。詳しくはカスタムジョブ統合ガイドをご参照ください。

ジョブの読み込み順と優先

ジョブの読み込み順序は保証されません。ジョブ間の依存関係は events と alternateJobId で表現し、読み込み順序に依存しないでください。

同一のジョブ id が複数のソースに存在する場合 (例: ファイルとAPIの両方)、エージェントの最終更新優先の挙動により、どの定義が有効かが決まります。曖昧さを避けるため、ファイル (ポリシー管理) または API のいずれか一方を正とするソースにしてください。

MQTTサブスクリプションとパブリッシュ権限

MQTTで通信する必要があるジョブタスクは、個々のタスク定義の内側ではなく、ジョブルートオブジェクトの mqttTopics ブロックでトピック権限を宣言します。

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

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

ブローカーは実行時に allowedPublications と allowedSubscriptions を適用します。MQTT接続自体が成功していても、宣言リストにないトピックへのpublishまたはsubscribeは拒否されます。適用モデル全体およびプラグイン宣言との比較については、ジョブとプラグイン: MQTTトピックの権限をご参照ください。

まとめ

プラグイン

ジョブ

構成ファイル

Plugins/{PluginName}.json

Jobs/{job-id}.json

検出

起動時に Plugins/ からスキャン

起動時に Jobs/ からスキャン、ファイル変更時も再スキャン

MQTT権限

Subscription + metadata.mqttTopics

ジョブルートの mqttTopics

ライフサイクル管理

autoStart、requiresMonitoring、autoRestart

schedule、events、またはAPIによるトリガー

新規コンポーネントの追加

JSONとバイナリを配置し、エージェントを再起動

Jobs/ にJSONを配置、または POST /api/Jobs を使用

前へジョブとプラグイン: MQTTトピックの権限次へジョブとプラグイン: 設定キー

最終更新 9 日前