ジョブの定義と形式

エージェント上のジョブ (自動化およびポリシー制御タスク) の定義とJSON形式

対象: エージェント上でジョブを作成、編集、トラブルシューティングするIT管理者向けです。

ジョブは、トリガーが発動したときに実行されるタスクの集合です。ジョブはポリシー制御、インベントリ、リスク評価、構成の処理、登録、通知、メンテナンスなどに使われます。各ジョブは1つのJSONファイルです。

ジョブファイルの場所と命名

• ディレクトリ: アプリケーションルート直下の Jobs/ (例: C:\Program Files\KeeperPrivilegeManager\Jobs または {approot}/Jobs)
• ファイル名: {job-id}.json。JSON内の id フィールドはファイル名 (.json を除く) と一致させる必要があります
• 例: Jobs/my-job.json には "id": "my-job" を含める必要があります

ジョブJSONの構造

{
  "id": "unique-job-id",
  "name": "Human-readable name",
  "description": "What the job does",
  "enabled": true,
  "priority": 5,
  "schedule": { ... },
  "events": [ ... ],
  "parameters": [ ... ],
  "tasks": [ ... ],
  "condition": { ... },
  "alternateJobId": null,
  "osFilter": { ... }
}

プロパティ	型	説明
id	string	一意のジョブID。ファイル名と一致させる必要があります
name	string	ログや管理画面に表示する名前
description	string	任意の説明
enabled	boolean	false のとき、トリガーに関係なく実行対象外
priority	number	1〜10。複数のジョブが同時に対象になる場合、数値が大きいほど優先
schedule	object	タイマーベースのトリガー (間隔、cron、1回限り、カレンダー)。イベントのみのジョブでは省略
events	array	このジョブを起動するイベント名 (例: PolicyEvaluationPending、Startup)
parameters	array	名前、型、既定値、必須フラグを持つ入力パラメータ。タスク引数の置換に利用
tasks	array	実行するタスクの順序付きリスト
condition	object	任意。未充足時はジョブをスキップするか alternateJobId を実行
alternateJobId	string	任意。condition 未充足時に実行するジョブ
osFilter	object	任意。特定プラットフォーム (windows、linux、macOS) に限定

トリガー

ジョブは、宣言したトリガーのいずれかが発動したときに実行されます。スケジュールとイベントのトリガーを組み合わせることもでき、いずれも単独でジョブの実行につながります。

イベント

events 配列にはイベント名が指定されます。MQTT、内部のポリシー操作、またはカスタムイベントから一致するイベントが発行されると、ジョブがキューに入ります。一般的なイベント種別には Startup、PolicyEvaluationPending、カスタムMQTTイベント名などがあります。

スケジュール

1つのジョブで使用できるスケジュールモードは1種類のみです。

• Interval: スケジューラ起動時からN分ごとに実行。

  "schedule": { "intervalMinutes": 30 }

• Cron: 標準的な5フィールドのcron式 (分、時、日、月、曜日)。

  "schedule": { "cronExpression": "0 16 * * 2" }

• One-time: 指定のUTC日時に1回だけ実行。

  "schedule": { "runAt": "2025-01-15T10:00:00Z" }

• Calendar: 特定の曜日の特定時刻に実行。

  "schedule": { "calendar": [ { "daysOfWeek": [1], "time": "09:00" } ] }

タスク

tasks 配列はジョブの処理内容を定義します。タスクは順番に実行されます。タスクが失敗し、continueOnFailure が未設定の場合、ジョブは停止します。あるタスクの出力は、パラメータや出力参照を通じて後続のタスクへ渡せます。

各タスクは通常以下を含みます。

• id: ジョブ内で一意。
• command または executablePath: 実行するもの。
• arguments: コマンドライン引数。ジョブパラメータや {KeeperApiBaseUrl} などの組み込みトークンによる置換が可能。
• ExecutionType: タスクの実行コンテキスト。
• timeoutSeconds: 任意。エージェントがタスクを強制終了するまでの最大実行時間 (秒)。
• continueOnFailure: true のとき、このタスクが0以外の終了コードでもジョブは続行します。

実行タイプ

ExecutionType	実行方法
Service	エージェントサービスコンテキストで実行 (ユーザーデスクトップなし)。バックグラウンドおよびセキュリティ関連タスクの既定
User	現在のユーザーセッションで実行
UserElevated	ユーザーセッションで昇格して実行
UserDesktop	対話的なユーザーデスクトップセッションで実行
Http	プロセスを起動せず、エンドポイントへ HTTP または HTTPS リクエストを送信

scriptType を設定する場合、PowerShell、Bash、Python、Batch などのスクリプトも実行できます。利用できる値の正確な一覧は、お使いのエージェントのスキーマをご参照ください。

条件とプラットフォームの絞り込み

condition: タスクを実行する前に評価されるジョブレベルの条件です。条件を満たさない場合、ジョブはスキップされるか、alternateJobId で指定されたジョブが実行されます。

osFilter: ジョブの実行対象OSを限定します。osFilter が現在のプラットフォームを除外している場合、そのエージェントではジョブは実行されず、検証時の実行ファイル存在チェックもスキップされます。

"osFilter": {
  "windows": true,
  "linux": false,
  "macOS": false
}

検証と読み込み

• 検証: ジョブ JSON をリクエスト本文として POST /api/Jobs/validate に送ると、保存前に構造を検証できます。検証では、osFilter と一致するプラットフォームについて、参照されている実行ファイルが検証ホスト上に存在することを確認します。
• 読み込み: エージェントは起動時に Jobs/ ディレクトリからジョブを読み込み、ファイル変更時に再スキャンします。不正な JSON のジョブはスキップされ、エラーがログに記録されます。
• 登録とデプロイ: ジョブの検出と登録についてはジョブとプラグイン: 登録をご参照ください。カスタムジョブタスクのバイナリを端到端でデプロイする手順についてはカスタムジョブガイドをご参照ください。