ジョブとプラグイン: 設定キー
対象: appsettings.json を構成する統合担当者、または実行時に GET /api/PluginSettings/{pluginName} で設定を読み取る統合担当者向けです。
本ページでは、カスタムジョブおよびプラグイン統合で特に重要な設定キーを一覧します。実行中のバイナリからプラグイン設定APIを呼び出す手順の説明は、概要ページをご参照ください。プラグイン設定APIエンドポイントの完全なリファレンスは、HTTPリファレンスガイドをご参照ください。
設定のマージ方法
コンポーネントに対する実効設定は、以下の3つのソースを、優先度の高い順に適用されます。
統合ストレージ — ポリシーで適用された値、または
PUT /api/PluginSettings/{pluginName}/{settingName}で書き込まれた値。2および3より優先されます。ディスク上のプラグインJSON — 管理対象プラグインでは
Plugins/{PluginId}.json、エージェント全体の設定ではシステムレベルのJSONファイル。システム既定 — エージェントにコンパイル済みの組み込み既定。
ディスク上のJSONを直接解析するのではなく、常に GET /api/PluginSettings/{pluginName} で実効設定を読み取ってください。ディスク上のファイルは、統合ストレージのポリシー上書きを反映していない場合があります。
アプリケーション全体の設定 (appsettings.json)
appsettings.json)これらのキーはエージェントサービス実行ファイルの隣にある appsettings.json の Settings セクションにあります。変更を反映するにはサービスの再起動が必要です。
KestrelHttpsPort
integer
6889
ローカルAPI用HTTPSポート。ジョブ引数の置換で KeeperApiBaseUrl を組み立てる際に使用
KestrelHttpPort
integer
6888
ローカルAPI用HTTPポート。機密操作にはHTTPSを優先
AlternativeSignatures
string 配列
—
プロセス認証で信頼するAuthenticode証明書のサムプリント。ジョブ起動コンテキスト外でMQTTまたはプラグイン層のHTTPSアクセスが必要な場合、バイナリの署名証明書のサムプリントをここに追加
AllowedNonAdminExecutables
string 配列
—
プロセス所有者が管理者でないユーザーセッションで、プロセス認証を通過してよい実行ファイルのベース名 (パスなし、.exe なし)。ExecutionType: User または UserDesktop タスクにのみ関係。Service タスクでは不要
RepositoryPath
string
環境により異なる
エージェントの構成リポジトリの保存ディレクトリ。
PluginPath
string
Plugins
プラグインのルートフォルダ名またはパス。エージェントルートからの相対パス。
統合時によく構成するキーを示す Settings ブロックの例です。
署名済み Windows バイナリの Authenticode サムプリントを取得するには次を使います。
結果はスペースなしの40文字の16進文字列として使います。
MQTTブローカー設定 (MqttBrokerSettings)
MqttBrokerSettings)これらのキーはローカルMQTTブローカーを構成します。appsettings.json の MqttBrokerSettings 配下にあり、プラグイン設定では broker.host および broker.port として公開されます。
IpAddress
127.0.0.1
ブローカーのバインドおよび接続先アドレス。標準デプロイではループバック。
Port
8675
ブローカーのTCPポート。ブローカーはTLSを使用。平文TCPポートではない
バイナリ内にこれらの値をハードコードしないでください。実行時にプラグイン設定から読み取ることで、管理者による構成変更を取り込めます。
応答には、稼働中のエージェントが使用している実効の MqttBrokerSettings を反映した broker.host および broker.port が文字列値として含まれます。完全なコード例は概要ページをご参照ください。
実行時にプラグイン設定から読むキー
カスタムジョブタスクまたはプラグインが、起動時に GET /api/PluginSettings/KeeperPrivilegeManager から読み取るキーです。呼び出しにはプラグイン層の認証が必要で、エージェントが起動したプロセスから行う必要があります。
broker.host
MqttBrokerSettings:IpAddress
TLS接続先MQTTブローカーのホスト名またはIP
broker.port
MqttBrokerSettings:Port
MQTTブローカーのポート
エージェントのバージョンやポリシー構成によっては、ほかのキーも応答に現れます。バイナリが必要とするものだけを解釈してください。
コンポーネント固有のプラグインスコープ設定には、プラグイン自身のIDを使います。
これはプラグインの名前空間に保存された設定とシステム既定をマージして返します。システム全体のブローカー設定とは別に必要な構成の取得に使います。
ラストノウングッド (ConfigurationLkg)
ConfigurationLkg)ConfigurationLkg:Enabled
boolean
true のとき、エージェントは各ジョブのJSONの暗号化された参照コピーを保持し、Jobs/ ディレクトリのずれを監視。手編集したジョブファイルは参照コピーから復元される場合あり。有効時にジョブを確実に書き込むにはAPIまたは JobUpdate ポリシーを使用
ジョブのデプロイ方法を選ぶ前に、デプロイでラストノウングッドが有効かどうかを確認してください。詳細はカスタムジョブ統合ガイドをご参照ください。
変更の適用
appsettings.json の編集 (AlternativeSignatures、ポート、ブローカー設定)
エージェントサービスを再起動
PUT /api/PluginSettings/{id}/{key} によるプラグイン設定
以降の読み取りから即時反映。プラグインが設定をキャッシュする場合は再読み取りまたは再起動が必要なことがあります
ポリシーで配信される設定
エンドポイントで構成ポリシープロセッサが実行されたときに適用
ディスク上のプラグイン JSON
エージェント再起動後に実効化、または POST /api/PluginSettings/{id}/revert でファイルを統合ストレージへ再インポートした後
最終更新