# プラグイン: 最小構成 (Windows)

**想定読者:** Windowsエンドポイントに常駐型の管理プラグインを登録する統合担当者。

本例は、Windows向け実行ファイルに対して妥当な最小限のプラグインJSONを示します。`autoStart` を有効にし、主たるMQTTサブスクリプション、監視と自動再起動、および `KeeperLogger` へのパブリッシュ許可を含みます。デプロイ前にプレースホルダを実際の値に置き換え、出発点としてご利用ください。LinuxおよびmacOS向けは、[プラグイン: 最小構成 (Linux)](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-minimal-linux.md) および[プラグイン: 最小構成 (macOS)](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-minimal-macos.md) をご参照ください。

コンポーネントがスケジュールで動作して終了するだけで常駐しない場合はジョブタスク向けです。まずは[ジョブ: 最小構成 (Windows)](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/job-minimal-windows.md) をご参照ください。

## プラグインのJSON <a href="#the-plugin-json" id="the-plugin-json"></a>

```json
{
  "id": "MyBridge",
  "name": "My Bridge",
  "description": "Long-running bridge component.",
  "version": "1.0.0",

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge.exe",
  "supportedPlatforms": ["Windows"],

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

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger"],
      "subscribe": ["MyBridge", "MyBridge/Commands/+"]
    }
  },

  "startupPriority": 60,
  "autoStart": true,
  "executionContext": "Service",
  "requiresMonitoring": true,
  "autoRestart": true
}
```

## 変更する箇所 <a href="#what-to-change" id="what-to-change"></a>

<table><thead><tr><th width="280.6666259765625">フィールド</th><th>内容</th></tr></thead><tbody><tr><td><code>id</code></td><td>安定した一意の識別子。プラグインのキーとして <code>/api/PluginSettings/{id}</code> に使われ、ファイル名とも一致させます (<code>"id": "MyBridge"</code> なら <code>MyBridge.json</code>)。デプロイ後に <code>id</code> を変える場合は移行手順を管理者と調整したうえで実施してください。変更すると、旧IDに紐づく設定は引き継がれません。</td></tr><tr><td><code>name</code></td><td>ログおよび管理画面に表示する名称</td></tr><tr><td><code>version</code></td><td>バイナリのセマンティックバージョン。診断と変更追跡のため、リリースごとに更新します。</td></tr><tr><td><code>executablePath</code></td><td>エージェントルートからの相対パス、または絶対パス。Windowsでのエージェントのデフォルトルートは <code>C:\Program Files\KeeperPrivilegeManager</code> のため、<code>bin/MyBridge/MyBridge.exe</code> は <code>C:\Program Files\KeeperPrivilegeManager\bin\MyBridge\MyBridge.exe</code> に解決されます。</td></tr><tr><td><code>Subscription.Topic</code></td><td>当該プラグインの主たるMQTTトピック。慣例としてプラグインの <code>id</code> を使います。エージェントに登録された全プラグインの間で一意である必要があります。</td></tr><tr><td><code>metadata.mqttTopics.publish</code></td><td>バイナリがパブリッシュするすべてのMQTTトピック。ログメッセージを出す場合は <code>KeeperLogger</code> を含めます。その他の出力トピックもここに列挙します。ブローカーが実行時にこの一覧を強制します。</td></tr><tr><td><code>metadata.mqttTopics.subscribe</code></td><td>主たる <code>Subscription.Topic</code> 以外にバイナリがサブスクライブするすべてのトピック。<code>Commands/+</code> パターンはコマンド形式トピックの慣例です。使わない場合は置き換えるか削除します。</td></tr><tr><td><code>startupPriority</code></td><td>他プラグインとの起動順。小さいほど先に起動します。他のカスタム構成要素への依存がないカスタムプラグインでは、<code>60</code> を妥当なデフォルトにできます。</td></tr></tbody></table>

## 動作の要点 <a href="#how-this-works" id="how-this-works"></a>

**`pluginType: Executable`** は、オーケストレーターにバイナリを子プロセスとして起動するよう指示します。単体実行ファイル向けの正しいタイプです。

**`executablePath`** はプラグイン用ディレクトリではなくエージェントルートからの相対です。`bin/MyBridge/MyBridge.exe` は `Plugins/` ツリーの外にバイナリを置く例で、プラグイン関連ディレクトリ内の実行ファイルに適用される厳しい証明書パス検査を避けられます。デプロイレイアウトがこの慣例に合わない場合は絶対パスを使います。

**`Subscription`** はオーケストレーターが当該プラグインを識別するために使う主たるMQTTトピックです。失われたり重複してはならないコマンドには `Qos: 2` を設定します。`CleanSession: true` は多くのプラグインで妥当で、再接続時にブローカーが前セッションのキュー済みメッセージを破棄し、再生しないことを意味します。

**`metadata.mqttTopics`** は、バイナリが実際にパブリッシュ／サブスクライブする内容と正確に一致させる必要があります。ブローカーが実行時にこれらの一覧を強制し、宣言外のパブリッシュやサブスクライブは拒否されます。ジョブタスクとは異なり、プラグインにジョブレベルの別ブロック `mqttTopics` はなく、宣言はすべて `metadata` 配下に置きます。

**`autoStart: true`** により、エージェント起動時にオーケストレーターがプラグインを起動します。オンデマンドやジョブによる起動のみにしたい場合は `false` にします。そのパターンは[プラグイン: 手動起動](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-manual-start.md)をご参照ください。

**`requiresMonitoring: true`** と **`autoRestart: true`** を併用すると、オーケストレーターがプロセスを監視し、異常終了時に再起動します。常駐が必須の本番プラグインでは両方を有効にします。意図的な終了条件がある場合は、ログでクラッシュと区別できる終了コードにします。

**`executionContext: Service`** はプラグインをエージェントのサービスアカウントで実行します。対話的なユーザーセッションを要しないバックグラウンド構成要素向けです。

## デプロイ前に <a href="#before-you-deploy" id="before-you-deploy"></a>

1. **バイナリに署名する:** Windowsではプラグイン用バイナリがジョブタスク用より厳しい信頼チェックの対象になります。Authenticode証明書で署名し、必要に応じて `appsettings.json` の `Settings:AlternativeSignatures` にサムプリントを追加します。
2. **バイナリを配置する:** プラグイン登録前に `executablePath` が解決する場所へ置きます。
3. **JSONファイルを配置する:** `{AgentRoot}\Plugins\MyBridge.json` に置き、ファイル名を `id` と一致させます。
4. **管理者と手順をすり合わせる:** JSONを置いてエージェントを再起動するのが一般的ですが、パッケージングやポリシー要件は環境により異なります。
5. **エージェントサービスを再起動する:** 両方のファイルを配置したあと再起動し、オーケストレーターが新しい登録を読み込みます。

## 検証 <a href="#verify" id="verify"></a>

エージェント再起動後、ログでプラグイン名を確認して起動に成功したことを確かめます。続いて、バイナリからの `KeeperLogger` パブリッシュがオペレーター向けのログ画面に表示されることを確認し、MQTTの疎通を裏づけます。

プラグインの実効設定を読み取る例です。

```powershell
Invoke-RestMethod -Method Get `
  -Uri "https://127.0.0.1:6889/api/PluginSettings/MyBridge" `
  -Certificate $pluginClientCert
```

この呼び出しにはプラグイン階層の認証が必要で、エージェントが起動したプロセスからでなければなりません。任意のスクリプトからではなく、プラグインバイナリ内の起動時に実行し、設定取得までの経路が正しく機能しているか確認します。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-minimal-windows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.