プラグイン: 手動起動

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

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

本例のパスはWindows向けです。他OSではプラグイン: 最小構成 (Linux) またはプラグイン: 最小構成 (macOS) のパス記載に合わせて置き換えてください。

プラグインの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
}

変更する箇所

フィールド

内容

id

ファイル名と一致する安定した一意の識別子 ("id": "MyOnDemand" なら MyOnDemand.json)。

executablePath

バイナリへのフルパスまたは相対パス。

supportedPlatforms

対象プラットフォーム

Subscription.Topic

当該プラグインの主たるMQTTトピック。慣例としてプラグインの id を使います。

metadata.mqttTopics.publish

実行時にバイナリがパブリッシュするすべてのトピック。自動起動しない場合でも正確に宣言します。バイナリが動いているときは常にブローカーが強制します。

metadata.mqttTopics.subscribe

主たる Subscription.Topic 以外にバイナリがサブスクライブするすべてのトピック。

動作の要点

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

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

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

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

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

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

ジョブタスク経由で起動した場合、バイナリはプラグインのプロセス信頼ルールではなくジョブタスクのプロセス信頼ルールの下で動きます。MQTTクライアントIDの形式、トピック権限チェック、プラグイン設定の認証は、その実行ではジョブタスク側の経路に従います。詳細はカスタムジョブ統合ガイドのジョブタスクのプロセス信頼に関する記述をご参照ください。

デプロイ前に

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

検証

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

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

前へプラグイン: MQTTでのコマンドとレスポンス次へプラグイン: Install Launcher

最終更新 4 日前