ジョブの定義と形式

エージェント上のジョブ (自動化およびポリシー制御タスク) の定義と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または内部イベント由来)。該当イベントが公開されるとジョブがキューに入ります。例: ポリシー評価保留、起動、カスタムイベント名。

スケジュール:

• 間隔: "schedule": { "intervalMinutes": 30 } — 30分ごと。

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

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

• カレンダー: "schedule": { "calendar": [ { "daysOfWeek": [1], "time": "09:00" } ] } — 例: 毎週月曜09:00 (UTC)。

1ジョブあたり、使うスケジュールの種類は1つにしてください。

---

タスク

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

• id — ジョブ内で一意。

• command または executable — 実行するもの (パスまたはコマンド名)。

• arguments — コマンドライン引数 (パラメータ置換が可能)。

• executionType — 例: Service、User、Elevated、Desktop、またはHTTP (HTTPリクエストタスク用)。

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

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

• Service — サービスコンテキストで実行 (ユーザーデスクトップなし)。

• User — ユーザーコンテキストで実行。

• Elevated — 昇格して実行 (ポリシーに従う)。

• Desktop — 必要に応じて対話的/ユーザーデスクトップ上で実行。

• HTTP — エンドポイントへのHTTP/HTTPSリクエスト (例: ローカルAPIまたは外部)。

タスクは製品のサポートに応じて script (PowerShell、Bash) や built-in 型にもなり得ます。正確なタスクの形は、ジョブの例またはスキーマをご確認ください。

---

ジョブでできること

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

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

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

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

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

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

---

検証と読み込み

• 検証: 一部の構成では、保存前にジョブJSONを検証するAPI (例: JSON本文を付けて /api/Jobs/validate へPOST) が利用できます。

• 読み込み: エージェントは起動時およびファイル変更時に Jobs/ ディレクトリからジョブを読み込みます (製品の動作に依存します)。新規または更新されたJSONは取り込まれます。不正なJSONのジョブはスキップされ、エラーがログに記録されることがあります。

• 登録: ジョブの検出と登録の方法は プラグインとジョブの登録をご参照ください。