# ジョブの定義と形式

**対象:** エージェント上でジョブ (自動化およびポリシー制御タスク) を作成、編集、トラブルシューティングする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` が現在のプラットフォームを除外している場合、そのエージェントではジョブは実行されず、検証時の実行ファイル存在チェックもスキップされます。

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

***

### 検証と読み込み

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


---

# 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/reference/jobs-definition-and-format.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.