# HTTPリファレンスガイド

## HTTPリファレンス <a href="#http-reference" id="http-reference"></a>

本ページは、統合で利用するローカルHTTPS APIのうち、次の2つをまとめたリファレンスです。**プラグイン設定API**は、実行中のジョブタスクやプラグインから実行時の構成を読むために呼び出します。**ジョブ管理API**は、デプロイ用ツールからジョブの作成・更新・トリガーに使います。

各エンドポイントをいつ・なぜ呼ぶかは[カスタムジョブ統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-job-guide.md)を、管理プラグイン向けのプラグイン設定は[カスタムプラグイン統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-plugin-guide.md)をご参照ください。デプロイスクリプトを書くときやエンドポイントの形を確認するときは、本ページで確認できます。

## ベースURLとTLS <a href="#base-url-and-tls" id="base-url-and-tls"></a>

エージェントのAPIはループバック上にのみ公開されます。リモートからはアクセスできません。

<table><thead><tr><th width="164.333251953125">設定</th><th width="157.666748046875">一般的な値</th><th>出所</th></tr></thead><tbody><tr><td>HTTPSポート</td><td><code>6889</code></td><td><code>appsettings.json</code> の <code>Settings:KestrelHttpsPort</code></td></tr><tr><td>HTTPポート</td><td><code>6888</code></td><td><code>appsettings.json</code> の <code>Settings:KestrelHttpPort</code></td></tr><tr><td>TLS証明書</td><td>自己署名、ローカル生成</td><td>管理者に確認。組織のCAバンドルが配布されていれば利用</td></tr></tbody></table>

API呼び出しはすべてHTTPSを使います。ベースURLは次のとおりです。

```
https://127.0.0.1:{KestrelHttpsPort}
```

多くのインストールではエージェントは自己署名TLS証明書を使います。ループバックから接続するHTTPクライアントは、管理者がエクスポートしたCAバンドルでその証明書を明示的に信頼するか、セキュリティポリシーに従いループバック接続では証明書検証を無効にします。機密操作にHTTPポートは使わず、HTTPSを推奨します。

値をハードコードする前に、デプロイチームで実際のポートを確認してください。ジョブタスクでは実行時に正しいベースURLを渡すために `{KeeperApiBaseUrl}` の引数置換を使い、`127.0.0.1:6889` の固定は避けます。

## 認可階層 <a href="#authorization-tiers" id="authorization-tiers"></a>

リクエストはすべて、エージェントの認可ミドルウェアによって、求められる認可階層に分類されます。統合で扱う2階層は次のとおりです。

<table><thead><tr><th width="97.666748046875">階層</th><th width="398.333251953125">呼び出し可能な主体</th><th>対象</th></tr></thead><tbody><tr><td><strong>管理用 (Admin)</strong></td><td>管理用資格情報で認証されたデプロイ用ツール。多くの場合、Keeperデプロイチームがプロビジョニングしたクライアント証明書による相互TLS</td><td>ジョブ管理の全エンドポイント: 作成、更新、削除、検証、トリガー、再読み込み</td></tr><tr><td><strong>プラグイン (Plugin)</strong></td><td>エージェントが起動し信頼済みとして登録したプロセス。ジョブランナーが起動したジョブタスク、またはオーケストレータが起動した管理プラグイン</td><td>プラグイン設定の全エンドポイント: マージ済み設定の読取、個別キーの読み書き、revert</td></tr></tbody></table>

実務上の要点は、**呼び出し主体が別々であり、同一バイナリの2モードではない**ということです。

ジョブタスクのバイナリは、実行中にプラグイン設定 (プラグイン階層) を呼び出します。デプロイスクリプトはジョブ管理API (管理用階層) を外部から、CI、ワークステーション、管理用資格情報付きの自動化ツールから呼び出します。タスクバイナリの内側から `/api/Jobs` を呼び出すことや、任意のシェルやスクリプトから `/api/PluginSettings/...` が動くことを想定しないでください。

TLSは成功しているのに `403` になる場合は、証明書やネットワークではなく**認可階層**の問題です。エンドポイントが要求する階層と、呼び出しプロセスがそれを満たすかを確認してください。

## プラグイン設定API <a href="#plugin-settings-api" id="plugin-settings-api"></a>

`/api/PluginSettings` 配下のすべてのエンドポイントには**プラグイン階層**の認可が必要です。呼び出し元は、エージェントが起動し登録したプロセス、すなわちジョブタスクまたは管理プラグインである必要があります。手動起動 (シェル、CIランナー、テストスクリプトからの実行) は `403` になります。

### エンドポイント <a href="#plugin-settings-endpoints" id="plugin-settings-endpoints"></a>

<table><thead><tr><th width="101">メソッド</th><th width="198.666748046875">パス</th><th width="185.666748046875">リクエストボディ</th><th>レスポンス</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/PluginSettings/{pluginName}</code></td><td>—</td><td><code>200</code> — 文字列キーから文字列値へのフラットなJSON (マージ後の有効設定)</td></tr><tr><td><code>GET</code></td><td><code>/api/PluginSettings/{pluginName}/{settingName}</code></td><td>—</td><td><code>200</code> — 単一の設定値</td></tr><tr><td><code>PUT</code></td><td><code>/api/PluginSettings/{pluginName}/{settingName}</code></td><td><code>PluginSettingValue</code> JSON</td><td>成功時 <code>200</code></td></tr><tr><td><code>POST</code></td><td><code>/api/PluginSettings/{pluginName}/revert</code></td><td>—</td><td><code>200</code> — 該当プラグインのディスク上JSONを統合ストレージへ再インポート</td></tr><tr><td><code>POST</code></td><td><code>/api/PluginSettings/revert-all</code></td><td>—</td><td><code>200</code> — すべてのプラグインをディスク上JSONから再インポート</td></tr><tr><td><code>GET</code></td><td><code>/api/PluginSettings/{pluginName}/status</code></td><td>—</td><td>構成変更とハッシュの状態</td></tr></tbody></table>

### `{pluginName}` の値 <a href="#pluginname-values" id="pluginname-values"></a>

プラグイン名に `KeeperPrivilegeManager` を使うと、システム全体のマージ済み設定 (`broker.host` と `broker.port` を含む) を読めます。MQTTブローカーアドレスが必要なジョブタスクでは標準的な呼び出しです。

独自プラグインの `id` (例: `MyBridge`) を指定すると、そのプラグインにスコープされた設定の読み書きができます。

### `GET /api/PluginSettings/{pluginName}` のレスポンス形 <a href="#response-shape-for-get" id="response-shape-for-get"></a>

レスポンスは値がすべて文字列のフラットなJSONオブジェクトです。

```json
{
  "broker.host": "127.0.0.1",
  "broker.port": "8675",
  "some.other.key": "value"
}
```

統合が必要とするキーだけを解釈してください。エージェントのバージョンやポリシー構成により、他のキーが含まれることがあります。

### `PUT` のリクエストボディ <a href="#put-request-body" id="put-request-body"></a>

単一の設定を書き込む例:

```json
{
  "value": "new-value-here"
}
```

### よくある失敗 (プラグイン設定) <a href="#plugin-settings-common-failures" id="plugin-settings-common-failures"></a>

<table><thead><tr><th width="126.666748046875">レスポンス</th><th>原因</th></tr></thead><tbody><tr><td><code>403</code></td><td>プラグインとして認証されていない。エージェントが起動したプロセスではない、または起動済みプロセス登録簿への登録がまだ完了していない。起動直後の失敗であればリトライを追加する。</td></tr><tr><td><code>404</code></td><td>プラグイン名がエージェントのプラグインレジストリに存在しない。デプロイと名前の完全一致を確認する。</td></tr></tbody></table>

## ジョブ管理API <a href="#job-management-api" id="job-management-api"></a>

`/api/Jobs` 配下のエンドポイントは、特記がない限り**管理用階層**の認可が必要です。クライアント証明書、相互TLS、その他の管理用資格情報など、実際の認証方式はデプロイごとに異なります。環境用の資格情報とツールはKeeperデプロイチームから提供されます。

### エンドポイント <a href="#job-management-endpoints" id="job-management-endpoints"></a>

<table><thead><tr><th width="105.6666259765625">メソッド</th><th width="180">パス</th><th width="143.6666259765625">リクエストボディ</th><th>レスポンス</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/Jobs</code></td><td>—</td><td><code>200</code> — <code>jobs</code> 配列、<code>count</code>、<code>message</code> を含むオブジェクト</td></tr><tr><td><code>GET</code></td><td><code>/api/Jobs/{jobId}</code></td><td>—</td><td><code>200</code> — ジョブ定義JSON。見つからない場合は <code>404</code></td></tr><tr><td><code>POST</code></td><td><code>/api/Jobs</code></td><td>ジョブJSON</td><td>成功時 <code>200</code>。不正な場合は検証エラーで <code>400</code></td></tr><tr><td><code>PUT</code></td><td><code>/api/Jobs/{jobId}</code></td><td>ジョブJSON</td><td>成功時 <code>200</code>。ジョブが存在しない場合は <code>404</code></td></tr><tr><td><code>DELETE</code></td><td><code>/api/Jobs/{jobId}</code></td><td>—</td><td>成功時 <code>200</code>。見つからない場合は <code>404</code></td></tr><tr><td><code>POST</code></td><td><code>/api/Jobs/validate</code></td><td>ジョブJSON</td><td><code>200</code> — <code>valid</code>、<code>errors</code>、<code>warnings</code>、<code>jobId</code> を含むオブジェクト。保存はしない</td></tr><tr><td><code>POST</code></td><td><code>/api/Jobs/{jobId}/trigger</code></td><td>任意のJSONオブジェクト</td><td><code>200</code> — 任意のイベント文脈で実行をトリガー。ジョブが無効なら <code>400</code></td></tr><tr><td><code>POST</code></td><td><code>/api/Jobs/{jobId}/run</code></td><td>—</td><td><code>200</code> — 非同期実行をトリガー。ジョブが無効なら <code>400</code></td></tr><tr><td><code>POST</code></td><td><code>/api/Jobs/reload</code></td><td>—</td><td><code>200</code> — ディスクからジョブ定義を再読み込み</td></tr></tbody></table>

### 特定エンドポイントの注記 <a href="#notes-on-specific-endpoints" id="notes-on-specific-endpoints"></a>

**`POST /api/Jobs`** — ジョブの作成または更新。完全なジョブバリデータを実行し、呼び出し時点でジョブJSONに記載されたパスにタスクの実行ファイルが存在する必要があります。このエンドポイントを呼ぶ前にバイナリをデプロイしてください。ジョブの `osFilter` が現在のOSを除外している場合、その実行ではバイナリ存在チェックはスキップされます。

**`POST /api/Jobs/validate`** — 検証内容は `POST /api/Jobs` と同じで、ディスクへの書き込みは行いません。本番エージェントに対してコミット前にジョブJSONを試験するときに使います。レスポンスボディに有効かどうかと、エラーまたは警告の一覧が含まれます。

**`PUT /api/Jobs/{jobId}`** — URLの `id` が権威です。ジョブJSON本文の `id` が異なる場合はURLの値で上書きされます。

**`POST /api/Jobs/{jobId}/trigger`** — テスト中に手動でジョブを実行する際の推奨方法です。任意のリクエストボディでイベント文脈をキーと値のJSONとして渡せます。空のボディ (`{}`) も受け付けます。

**`POST /api/Jobs/reload`** — エージェントに `Jobs/` ディレクトリからジョブ定義の再読み込みを強制します。許可された経路でディスクにファイルを置いた直後に、エージェントを再起動せず変更を取り込むときに使います。

### `{jobId}` の形式 <a href="#jobid-format" id="jobid-format"></a>

パスセグメント内のジョブIDはURLエンコードされます。ハイフンは使用できます。ジョブIDにアンダースコアは使わないでください。MQTTブローカーはクライアントIDをアンダースコアで分割してジョブIDを取り出すため、IDにアンダースコアがあると解析が壊れます。詳細は[カスタムジョブ統合ガイド](/keeperpam/jp/endpoint-privilege-manager/integrations/custom-job-guide.md#step-3-form-the-mqtt-client-id)をご参照ください。

## よくある失敗 (ジョブ管理) <a href="#common-failures" id="common-failures"></a>

<table><thead><tr><th width="114">レスポンス</th><th>原因</th></tr></thead><tbody><tr><td><code>400</code></td><td>検証失敗。検証ホスト上にバイナリがない、JSONが不正、必須フィールド欠落など。レスポンスボディの <code>errors</code> 配列を確認する。</td></tr><tr><td><code>403</code></td><td>管理用資格情報がない、または受理されない。このエージェント用のクライアント証明書や認証トークンが正しいか、デプロイチームに確認する。</td></tr><tr><td><code>404</code></td><td>ジョブIDが見つからない。未作成かID不一致。<code>GET /api/Jobs</code> で存在を確認する。</td></tr></tbody></table>

## 基本的な例 <a href="#basic-examples" id="basic-examples"></a>

以下はPowerShellとcurlの例です。証明書のパス、URL、JSONファイルは環境に合わせて置き換えてください。

### 保存せずにジョブを検証する (PowerShell) <a href="#validate-a-job-without-saving-powershell" id="validate-a-job-without-saving-powershell"></a>

```powershell
Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/validate" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-job.json)
```

### ジョブを作成する (PowerShell) <a href="#create-a-job-powershell" id="create-a-job-powershell"></a>

```powershell
Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body (Get-Content -Raw .\my-job.json)
```

### ジョブ実行を手動でトリガーする (PowerShell) <a href="#trigger-a-job-run-manually-powershell" id="trigger-a-job-run-manually-powershell"></a>

```powershell
Invoke-RestMethod -Method Post `
  -Uri "https://127.0.0.1:6889/api/Jobs/my-job-id/trigger" `
  -ContentType "application/json" `
  -Certificate $adminClientCert `
  -Body "{}"
```

### 登録済みジョブを一覧する (curl) <a href="#list-all-registered-jobs-curl" id="list-all-registered-jobs-curl"></a>

```bash
curl -s https://127.0.0.1:6889/api/Jobs \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem
```

### ジョブを作成する (curl) <a href="#create-a-job-curl" id="create-a-job-curl"></a>

```bash
curl -s -X POST https://127.0.0.1:6889/api/Jobs \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem \
  -H "Content-Type: application/json" \
  -d @my-job.json
```

### ジョブを削除する (curl) <a href="#delete-a-job-curl" id="delete-a-job-curl"></a>

```bash
curl -s -X DELETE https://127.0.0.1:6889/api/Jobs/my-job-id \
  --cert /path/to/client.pem \
  --key /path/to/client.key \
  --cacert /path/to/ca.pem
```


---

# 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/http-reference-guide.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.