ジョブの定義と形式

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

対象: エージェント上でジョブ (自動化およびポリシー制御タスク) を作成、編集、トラブルシューティングするIT管理者向けです。

---

ジョブとは

ジョブとは、トリガーが発動したときに実行されるタスクの集合として定義されたものです。トリガーには以下の種類があります。

• イベント 例: MQTT (ポリシー評価保留、起動、カスタムイベント)。

• スケジュール 間隔 (N分ごと)、cron、1回限りのrun-at、カレンダー。

• API オンデマンドでジョブを実行する管理用エンドポイント。

ジョブはポリシー制御 (例: 昇格の起動、承認要求)、インベントリ、リスク評価、構成の処理、登録、通知、メンテナンスなどに使われます。各ジョブは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、runAt、カレンダー) です。イベントのみのジョブでは省略します。
events	array	このジョブを起動するイベント名 (例: PolicyEvaluationPending、Startup) です。
parameters	array	入力パラメータ (名前、型、既定値、必須フラグ) です。
tasks	array	実行するタスクの順序付きリストです。
condition	object	任意です。満たさない場合はジョブをスキップするか、代替ジョブを実行できます。
alternateJobId	string	任意です。条件を満たさないときに実行するジョブです。
osFilter	object	任意です。Windows、Linux、macOSのいずれかまたは組み合わせに限定します。

---

トリガー

イベント:

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

スケジュール:

• Interval: "schedule": { "intervalMinutes": 30 } — 30分ごとに実行

• Cron: "schedule": { "cronExpression": "0 16 * * 2" } — 5フィールドのcron形式 (例: 毎週火曜日16:00)

• One-time: "schedule": { "runAt": "2025-01-15T10:00:00Z" } — 指定のUTC時刻に1回だけ実行。

• Calendar: "schedule": { "calendar": [ { "daysOfWeek": [1], "time": "09:00" } ] } — 例: 毎週月曜日09:00 (UTC)。

1つのジョブにつき、使用できるスケジュールタイプは1種類のみです。

---

タスク

tasksはタスクオブジェクトの配列です。各タスクは通常以下を含みます。

• id — ジョブ内で一意。

• command または executablePath — 実行するもの。

• arguments — コマンドライン引数。ジョブパラメータや {KeeperApiBaseUrl} などの組み込みトークンによる置換に対応します。

• ExecutionType — タスクの実行コンテキスト。

• timeoutSeconds — 任意。エージェントがタスクを強制終了するまでの最大実行時間 (秒)。

• continueOnFailure — true のとき、このタスクが0以外の終了コードでもジョブは続行します。

タスクは順番に実行されます。あるタスクの出力は、後続のタスクで利用できます (パラメータや出力参照など)。タスクが失敗し、continueOnFailure が未設定の場合、ジョブは停止します。

実行タイプ (代表的なもの):

• Service — エージェントサービスコンテキストで実行 (ユーザーデスクトップなし)。バックグラウンドおよびセキュリティ関連タスクの既定。

• User — 現在のユーザーセッションで実行。

• UserElevated — ユーザーセッションで昇格して実行。

• UserDesktop — 対話的なユーザーデスクトップセッションで実行。

• Http — プロセスを起動せず、エンドポイントへの HTTP または HTTPS リクエストを行います。

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

---

ジョブでできること

• 実行ファイルの実行 — 引数付きでバイナリまたはスクリプトを呼び出せます。

• HTTPエンドポイントの呼び出し — ローカルAPI (例: /api/...) または外部URLへGET/POSTできます。

• パラメータの利用 — イベントまたはトリガーデータをタスクへ渡せます (例: ユーザー、パス、ポリシー結果)。

• 条件分岐 — condition と alternateJobId で、コンテキストに応じた別ジョブを実行できます。

• プラットフォームの絞り込み — osFilter でWindows、Linux、macOSのいずれかでのみ実行できます。

ジョブの用途例として、ポリシー制御 (昇格、承認、リダイレクト、ファイルアクセス)、インベントリ、リスク評価、構成処理 (例: ProcessConfigurationPolicies)、登録/登録解除、通知、メンテナンス (ログ、クリーンアップ、バージョン情報) などがあります。

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

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

osFilter — ジョブを一致するオペレーティングシステムにだけ制限します。ジョブの osFilter が現在のプラットフォームを除外している場合、そのエージェントではジョブは実行されず、検証時の実行ファイル存在チェックもスキップされます。

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

---

検証と読み込み

• 検証: ジョブ JSON をリクエスト本文として POST /api/Jobs/validate に送ると、保存前に構造を検証できます。検証では、osFilter と一致するプラットフォームについて、参照されている実行ファイルが検証ホスト上に存在することを確認します。

• 読み込み: エージェントは起動時に Jobs/ ディレクトリからジョブを読み込み、ファイル変更時に再スキャンします。不正な JSON のジョブはスキップされ、エラーがログに記録されます。

• 登録とデプロイ: ジョブの検出と登録についてはプラグインとジョブの登録をご参照ください。カスタムジョブタスクのバイナリを端到端でデプロイする手順についてはカスタムジョブ統合ガイドをご参照ください。