# プラグイン: 手動起動

**想定読者:** オーケストレーターには登録するが、エージェント起動時には自動起動させたくないプラグインを扱う統合担当者。

`autoStart: false` にすると、プラグインは登録されます。オーケストレーターはその存在とトピック権限の宣言を認識し、`/api/PluginSettings/{id}` で設定を参照できますが、エージェント起動時にはバイナリは起動しません。明示的に起動されたときだけ動作します。常時稼働させたくないリソース集約型のコンポーネント、外部で起動順を厳密に制御したいプラグイン、メンテナンスや診断で時どきだけ使う構成要素などに向いています。

本例のパスはWindows向けです。他OSでは[プラグイン: 最小構成 (Linux)](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-minimal-linux.md) または[プラグイン: 最小構成 (macOS)](/keeperpam/jp/endpoint-privilege-manager/integrations/examples/plugin-minimal-macos.md) のパス記載に合わせて置き換えてください。

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

```json
{
  "id": "MyOnDemand",
  "name": "My On-Demand Component",
  "description": "Registered plugin that starts only when explicitly triggered.",
  "version": "1.0.0",

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

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

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger"],
      "subscribe": ["MyOnDemand"]
    }
  },

  "startupPriority": 80,
  "autoStart": false,
  "executionContext": "Service",
  "requiresMonitoring": false,
  "autoRestart": false
}
```

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

| フィールド                           | 内容                                                                        |
| ------------------------------- | ------------------------------------------------------------------------- |
| `id`                            | ファイル名と一致する安定した一意の識別子 (`"id": "MyOnDemand"` なら `MyOnDemand.json`)。         |
| `executablePath`                | バイナリへのフルパスまたは相対パス。                                                        |
| `supportedPlatforms`            | 出荷するプラットフォーム。                                                             |
| `Subscription.Topic`            | 当該プラグインの主たるMQTTトピック。慣例としてプラグインの `id` を使います。                               |
| `metadata.mqttTopics.publish`   | 実行時にバイナリがパブリッシュするすべてのトピック。自動起動しない場合でも正確に宣言します。バイナリが動いているときは常にブローカーが強制します。 |
| `metadata.mqttTopics.subscribe` | 主たる `Subscription.Topic` 以外にバイナリがサブスクライブするすべてのトピック。                       |

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

**`autoStart: false`** が本パターンの中核です。プラグインJSON、バイナリ、MQTTトピック宣言は自動起動型と同じで、エージェント起動時にオーケストレーターは登録だけ行い、バイナリは起動しません。

**`requiresMonitoring: false`** と **`autoRestart: false`** は自然な組み合わせです。監視と自動再起動は常駐が前提のプロセス向けです。オンデマンド構成では処理を終えて終了するか、明示停止まで動き続けるのが想定で、終了をクラッシュとして再起動の対象にしないようにします。

**`startupPriority: 80`** は `autoStart: false` のとき、エージェント起動時にプラグインが並列起動されないため、起動順には影響しません。慣例として低めの値にしておき、将来 `autoStart` を `true` にした場合はシーケンスの後ろで起動し、他構成要素の初期化に時間を与えます。

**メタデータのトピック宣言は正確に保つ:** 自動起動しなくても、エージェントがプラグインJSONを読み込んだ時点でトピック宣言はブローカーに登録されます。バイナリが動くとき (どの経路で起動しても) ブローカーが権限を強制するため、プレースホルダではなく実際の利用内容を宣言します。

**起動の経路:** `autoStart: false` のとき、オーケストレーターはエージェント起動時にプラグインを起動しません。起動には以下のいずれかが必要です。

* ジョブタスクが `executablePath` でバイナリを直接起動する方法 (よく使われます)。同じバイナリを指すタスクを含むジョブを、オンデマンドまたはスケジュールで用意します。
* 製品レベルのオーケストレーション (利用可否はエージェントのバージョンとデプロイ構成により異なるため、管理者へ確認してください)。

ジョブタスク経由で起動した場合、バイナリはプラグインのプロセス信頼ルールではなくジョブタスクのプロセス信頼ルールの下で動きます。MQTTクライアントIDの形式、トピック権限チェック、プラグイン設定の認証は、その実行ではジョブタスク側の経路に従います。詳細は[カスタムジョブ統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-job-guide.md#code-signing-and-process-trust)のジョブタスクのプロセス信頼に関する記述をご参照ください。

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

1. プラットフォーム要件に従いバイナリへ署名します。
2. `executablePath` が解決する場所へバイナリを置きます。
3. JSONファイルを `{AgentRoot}\Plugins\MyOnDemand.json` に置き、ファイル名を `id` と一致させます。
4. エージェントを再起動し、オーケストレーターにプラグインを登録させます。
5. 任意のトリガーを試す前に、ログで登録済みだが未実行であることを確認します。

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

エージェント再起動後、ログでプラグインが登録されている一方、プロセスとしては起動していないことを確認します。選んだトリガーで起動し、ログおよび `MyOnDemand` トピック上のMQTTで接続を確かめます。ジョブタスクで起動する場合は `POST /api/Jobs/{jobId}/trigger` を使い、期待どおりのログ出力を確認します。

```powershell
Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/my-trigger-job/trigger" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body "{}"
```


---

# 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-manual-start.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.