HTTPリファレンスガイド

HTTPリファレンス

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

各エンドポイントをいつ・なぜ呼ぶかはカスタムジョブ統合ガイドを、管理プラグイン向けのプラグイン設定はカスタムプラグイン統合ガイドをご参照ください。デプロイスクリプトを書くときやエンドポイントの形を確認するときは、本ページで確認できます。

ベースURLとTLS

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

設定

一般的な値

出所

HTTPSポート	6889	appsettings.json の Settings:KestrelHttpsPort
HTTPポート	6888	appsettings.json の Settings:KestrelHttpPort
TLS証明書	自己署名、ローカル生成	管理者に確認。組織のCAバンドルが配布されていれば利用

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

https://127.0.0.1:{KestrelHttpsPort}

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

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

認可階層

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

階層

呼び出し可能な主体

対象

管理用 (Admin)	管理用資格情報で認証されたデプロイ用ツール。多くの場合、Keeperデプロイチームがプロビジョニングしたクライアント証明書による相互TLS	ジョブ管理の全エンドポイント: 作成、更新、削除、検証、トリガー、再読み込み
プラグイン (Plugin)	エージェントが起動し信頼済みとして登録したプロセス。ジョブランナーが起動したジョブタスク、またはオーケストレータが起動した管理プラグイン	プラグイン設定の全エンドポイント: マージ済み設定の読取、個別キーの読み書き、revert

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

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

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

プラグイン設定API

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

エンドポイント

メソッド

パス

リクエストボディ

レスポンス

GET	/api/PluginSettings/{pluginName}	—	200: 文字列キーから文字列値へのフラットなJSON (マージ後の有効設定)
GET	/api/PluginSettings/{pluginName}/{settingName}	—	200: 単一の設定値
PUT	/api/PluginSettings/{pluginName}/{settingName}	PluginSettingValue JSON	成功時 200
POST	/api/PluginSettings/{pluginName}/revert	—	200: 該当プラグインのディスク上JSONを統合ストレージへ再インポート
POST	/api/PluginSettings/revert-all	—	200: すべてのプラグインをディスク上JSONから再インポート
GET	/api/PluginSettings/{pluginName}/status	—	構成変更とハッシュの状態

{pluginName} の値

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

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

GET /api/PluginSettings/{pluginName} のレスポンス形

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

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

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

PUT のリクエストボディ

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

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

よくある失敗 (プラグイン設定)

レスポンス

原因

403	プラグインとして認証されていない。エージェントが起動したプロセスではない、または起動済みプロセス登録簿への登録がまだ完了していない。起動直後の失敗であればリトライを追加する。
404	プラグイン名がエージェントのプラグインレジストリに存在しない。デプロイと名前の完全一致を確認する。

ジョブ管理API

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

エンドポイント

メソッド

パス

リクエストボディ

レスポンス

GET	/api/Jobs	—	200: jobs 配列、count、message を含むオブジェクト
GET	/api/Jobs/{jobId}	—	200: ジョブ定義JSON。見つからない場合は 404
POST	/api/Jobs	ジョブJSON	成功時 200。不正な場合は検証エラーで 400
PUT	/api/Jobs/{jobId}	ジョブJSON	成功時 200。ジョブが存在しない場合は 404
DELETE	/api/Jobs/{jobId}	—	成功時 200。見つからない場合は 404
POST	/api/Jobs/validate	ジョブJSON	200: valid、errors、warnings、jobId を含むオブジェクト。保存はしない
POST	/api/Jobs/{jobId}/trigger	任意のJSONオブジェクト	200: 任意のイベント文脈で実行をトリガー。ジョブが無効なら 400
POST	/api/Jobs/{jobId}/run	—	200: 非同期実行をトリガー。ジョブが無効なら 400
POST	/api/Jobs/reload	—	200: ディスクからジョブ定義を再読み込み

特定エンドポイントの注記

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} の形式

パスセグメント内のジョブIDはURLエンコードされます。ハイフンは使用できます。ジョブIDにアンダースコアは使わないでください。MQTTブローカーはクライアントIDをアンダースコアで分割してジョブIDを取り出すため、IDにアンダースコアがあると解析が壊れます。詳細はカスタムジョブ統合ガイドをご参照ください。

よくある失敗 (ジョブ管理)

レスポンス

原因

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

基本的な例

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

保存せずにジョブを検証する (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)

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)

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

登録済みジョブを一覧する (curl)

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)

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)

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