# 統合の概要

本ページでは、コードやJSONを書く前に全体像をつかめるよう、KEPM統合の背後にある概念と構成要素を説明します。[統合機能](/keeperpam/jp/endpoint-privilege-manager/integrations.md)のランディングページをまだ読んでいない場合は、そちらから始めてください。2つの統合パターンの定義と、着手前にデプロイチームから確認しておくべき事項がまとまっています。

***

### 主な用語 <a href="#key-terms" id="key-terms"></a>

以下の用語がKEPMでどう使われるかを押さえておくと、各ガイドを読むときの混乱を防げます。

**ジョブ** — エージェントの `Jobs/` ディレクトリ配下に `{job-id}.json` として保存されるJSONドキュメントです。ジョブは、*いつ* 何かを走らせるか (スケジュール、起動イベント、名前付きイベントトピック) と、*何を* 走らせるか (1つ以上のタスク) を定義します。カスタム実行ファイルのスケジュール実行と駆動の主たる手段です。

**タスク** — ジョブ内の1ステップです。実行ファイルまたはスクリプトを指し、実行方法 (`ExecutionType`)、引数、タイムアウト、失敗時の扱いを指定します。多くのカスタム統合ではジョブあたりタスクは1つです。

**プラグイン** — `Plugins/{PluginId}.json` に登録され、エージェントが第一級のプロセスとして管理するコンポーネントです。プラグインはエージェント制御のライフサイクル (起動、監視、再起動) を持ち、独自のアイデンティティに紐づくMQTTトピックを購読します。ジョブタスクのバイナリとは別概念です。エージェント横に配置しただけでは、実行ファイルが自動的にプラグインになるわけではありません。

**KeeperLogger** — 組み込みのエージェントコンポーネントで、MQTTトピック `KeeperLogger` を購読し、受信メッセージをエージェントのログパイプラインに書き込みます。実行ファイルはそのトピックへ構造化JSONをパブリッシュし、エージェントがメッセージをオペレーター向けのログ経路へ渡します。カスタムジョブタスクがプラットフォームへ結果を返す主な方法です。

**MQTTブローカー** — エージェントがループバックインターフェース上で動かすローカルメッセージブローカーです (デフォルトは `127.0.0.1:8675`、TLS)。タスクのバイナリを含むローカルコンポーネントが接続し、パブリッシュと購読を行います。アクセスはプロセス信頼で制御され、エージェントが起動した実行ファイル、または明示的に許可リストに載った実行ファイルだけが接続できます。

**プロセス信頼** — どのローカルプロセスがMQTTブローカーに接続し、プラグイン階層のHTTPSエンドポイントを呼び出せるかをエージェントが決める仕組みです。ジョブランナーがバイナリを起動すると、そのプロセスは直ちに登録され、バイナリからのMQTTおよびHTTPS呼び出しが許可されます。バイナリが別の経路で起動している場合 (手動、スクリプト経由など) は、代わりに証明書チェックに合格する必要があります。詳細は[カスタムジョブ統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-job-guide.md)をご参照ください。

## 統合の流れ <a href="#integrations-flow" id="integrations-flow"></a>

以下の流れは、ジョブがデプロイされてから、ログ行がオペレーターの画面に現れるまでの動きです。

```
┌─────────────────────────────────────────────────────────────────┐
│  KEPM Agent (on the endpoint)                                   │
│                                                                 │
│  Job runner reads Jobs/{job-id}.json                            │
│      │                                                          │
│      ├─ Evaluates triggers (schedule / Startup / event)         │
│      │                                                          │
│      └─ Starts your binary as a task process                    │
│             │   registers PID → process trust                   │
│             │   sets KEEPER_JOB_ID, KEEPER_JOB_NAME             │
│             │                                                   │
│             │   Your binary runs                                │
│             │       │                                           │
│             │       ├─ GET /api/PluginSettings/                 │
│             │       │   KeeperPrivilegeManager                  │
│             │       │   (Plugin-tier HTTPS)                     │
│             │       │   → reads broker.host, broker.port        │
│             │       │                                           │
│             │       └─ Connects to MQTT broker (TLS, loopback)  │
│             │           publishes to KeeperLogger               │
│             │                                                   │
│  KeeperLogger component                                         │
│      subscribes to "KeeperLogger" topic                         │
│      → writes messages to agent log pipeline                    │
│          → operators see log output                             │
└─────────────────────────────────────────────────────────────────┘
```

**エージェントが関所です。** バイナリがプロセス信頼、MQTTアクセス、実行時設定を得るのは、エージェントが起動したからであり、バイナリ単独の最初の動作によるものではありません。

**ブローカーアドレスをハードコードしません。** バイナリは起動時にプラグイン設定をHTTPSでエージェントに問い合わせ、エージェントが現在の `broker.host` と `broker.port` を返します。

**ログは標準出力ではなくMQTTを経由します。** バイナリは `KeeperLogger` MQTTトピックへ構造化JSONをパブリッシュします。以降の配信はエージェントが担います。

**MQTTの権限はジョブJSONで決まります。** バイナリがパブリッシュできるのは、ジョブの `mqttTopics.allowedPublications` に明示されたトピックに限られます。ブローカーが許可を強制し、権限の継承や暗黙の付与はありません。

## ジョブとプラグイン <a href="#jobs-vs-plugins" id="jobs-vs-plugins"></a>

2つの統合パターンは同じエージェントと同じMQTTブローカーを共有しますが、目的は根本的に異なります。

### ジョブを選ぶ場合 <a href="#use-a-job-when" id="use-a-job-when"></a>

| 必要なこと                       | ジョブでの対応                                                                      |
| --------------------------- | ---------------------------------------------------------------------------- |
| スケジュールまたはエージェント起動時にツールを実行する | `schedule.intervalMinutes` および/または `eventType: Startup` の `events` エントリを定義する |
| KeeperLoggerへログを送る          | ジョブに `mqttTopics.allowedPublications: ["KeeperLogger"]` を設定する                |
| 複数OSをサポートする                 | `osFilter` を設定し、各プラットフォームでは一致するタスクだけが実行されるようにする                              |
| バイナリへ実行時設定を渡す               | `tasks[].arguments` の `{KeeperApiBaseUrl}` など変数置換を使う                         |
| プラグインのオーバーヘッドなしでバイナリを配布する   | `Jobs/bin/{CommandName}/` に配置する。プラグイン用のJSONは不要                               |

ジョブタスクのバイナリは常駐である必要はありません。想定パターンは、起動して処理し、意味のある終了コードで終了することです。エージェントは終了コードを記録し、出力を取り込み、次に進みます。

### プラグインを選ぶ場合 <a href="#use-a-plugin-when" id="use-a-plugin-when"></a>

| 必要なこと                              | プラグインが合う理由                                                       |
| ---------------------------------- | ---------------------------------------------------------------- |
| プロセスを常時実行し続ける                      | プラグインJSONで `autoStart: true` と `requiresMonitoring: true` を指定できる |
| 失敗時にエージェントにプロセス再起動してほしい            | プラグインJSONで `autoRestart: true` を設定する                             |
| 名前付きの永続アイデンティティとしてMQTTトピックに購読する    | プラグインは主な `Subscription` を持ち、独自のトピック名前空間を持つ                       |
| プラグインID単位で取得できるコンポーネント別設定を置く       | `GET /api/PluginSettings/{yourPluginId}` でプラグイン設定を読める            |
| エージェントのネイティブ部品のように振る舞うコンポーネントを出荷する | パッケージ、署名、ライフサイクルはエージェント同梱コンポーネントと同等の前提で扱われる                      |

### 両方を使う場合 <a href="#when-to-use-both" id="when-to-use-both"></a>

両方が必要になるのは、ライフサイクルが明確に2つに分かれるときだけです。常時オンで監視されるプラグインとして登録された常駐デーモンと、別バイナリによる定期処理を行うスケジュールジョブが別々に存在するケースです。

同一実行ファイルをプラグインとジョブタスクの両方に登録しないでください。重複プロセス、MQTTクライアントIDの衝突、どの設定パスがバイナリの設定の主であるかの曖昧さを招きます。

### クイックリファレンス <a href="#quick-reference" id="quick-reference"></a>

| 質問                               | 回答                                                       |
| -------------------------------- | -------------------------------------------------------- |
| ジョブタスクに `Plugins/{id}.json` は必須か | いいえ。ジョブには `Jobs/{id}.json` とデプロイ済みバイナリだけで足ります            |
| ジョブタスクはMQTTへパブリッシュできるか           | はい。ジョブに `mqttTopics.allowedPublications` を宣言すれば可能です      |
| ジョブタスクはHTTPSでプラグイン設定を呼べるか        | はい。エージェントが起動した場合 (プラグイン階層の認可)                            |
| プラグイン登録が必要なのはどんなときか              | エージェント管理のライフサイクル、永続的なMQTT購読、プラグインスコープの設定のいずれかが必要な場合に限ります |

## エージェントがプロセスへ渡すもの <a href="#what-the-agent-provides-to-your-process" id="what-the-agent-provides-to-your-process"></a>

エージェントがバイナリをジョブタスクとして起動するとき、以下の環境変数を設定します。ただし、ジョブで `mqttTopics` に許可されたパブリケーションまたは購読が1つ以上ある場合に限ります。

| 変数                | 値                     | 用途                      |
| ----------------- | --------------------- | ----------------------- |
| `KEEPER_JOB_ID`   | ジョブJSONの `id` フィールド   | MQTTクライアントIDを組み立てるときに必須 |
| `KEEPER_JOB_NAME` | ジョブJSONの `name` フィールド | ログメッセージや診断に便利           |

`tasks[].arguments` に含めた場合、`{KeeperApiBaseUrl}` は環境変数ではなく置換後の引数値としてバイナリに渡されます。プラグイン設定のHTTPS呼び出しのベースURLとして使います。

エージェントは `broker.host`、`broker.port`、MQTT接続の詳細を環境変数として注入しません。バイナリは実行時にプラグイン設定から読み取る想定です。

***

### このあと読むドキュメント <a href="#now-what" id="now-what"></a>

**スケジュールまたはイベント駆動のツール** (最も一般的なケース) には、[カスタムジョブ統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-job-guide.md)をご参照ください。バイナリのビルドとデプロイ、ジョブJSONの作成、MQTT接続と構造化ログのパブリッシュまで、手順を一通り扱います。

**管理対象の常駐コンポーネント**の場合は、[カスタムプラグイン統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-plugin-guide.md)をご参照ください。

ジョブのデプロイをスクリプト化する準備ができたとき、またはバイナリ内からプラグイン設定を呼び出すときは、[HTTPリファレンス](/keeperpam/jp/endpoint-privilege-manager/integrations/http-reference-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/integrations/overview.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.