APIの使用
コマンダーサービスモードにおけるAPI利用
APIバージョン
このサービスでは、キュー設定に基づいて2種類のAPIバージョンを利用できます。
/api/v2/– キュー有効 (デフォルト): 非同期処理方式でリクエストが失われません/api/v1/– キュー無効 (v17.1.6以前): 同期方式で直接実行します
リクエストキューシステム (API v2)
キューが有効な場合(デフォルト)、サービスは非同期リクエストキューを利用し、次の特長を備えています。
順次処理: リクエストはFIFO順に1件ずつ処理
リクエスト追跡: 各リクエストに固有IDを付与し、状態を確認可能
リクエスト喪失防止: すべてのリクエストがキューに登録され確実に処理
結果取得: リクエストIDを使って非同期で結果を取得
キューAPIエンドポイント
リクエスト送信 (非同期)
curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{"command": "tree"}'応答 (202 Accepted)
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"message": "Request queued successfully. Use /api/v2/status/<request_id> to check progress, /api/v2/result/<request_id> to get results, or /api/v2/queue/status for queue info."
}リクエスト状態の確認
curl 'http://localhost:<port>/api/v2/status/<request_id>' \
--header 'api-key: <your-api-key>'応答
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"command": "tree",
"status": "completed",
"created_at": "2024-01-15T10:30:00.000000",
"started_at": "2024-01-15T10:30:01.000000",
"completed_at": "2024-01-15T10:30:03.000000"
}結果の取得
curl 'http://localhost:<port>/api/v2/result/<request_id>' \
--header 'api-key: <your-api-key>'応答 (完了済みリクエストの場合、api/v1 の直接実行と同様)
{
"result": "...",
"status": "success"
}キュー状態の取得
curl 'http://localhost:<port>/api/v2/queue/status' \
--header 'api-key: <your-api-key>'応答
{
"success": true,
"queue_size": 3,
"active_requests": 5,
"completed_requests": 12,
"currently_processing": "550e8400-e29b-41d4-a716-446655440000",
"worker_running": true
}リクエスト状態
queued- リクエストを受け付けてキューで待機中processing- 実行中completed- 正常に完了failed- 実行エラーexpired- 期限内に処理されずタイムアウト
キュー設定
キューシステムは以下のように構成されています。
queue_max_size: 100 # キューに登録できる最大リクエスト数
request_timeout: 300 # リクエストのタイムアウト (5 分)
result_retention: 3600 # 結果の保持期間 (1 時間)エラー応答
503 Service Unavailable - キューが満杯
404 Not Found - リクエスト ID が存在しない
500 Internal Server Error - コマンド実行エラー
429 Too Many Requests - レート制限に達した
直接実行 (API v1)
キューが無効の場合は、従来の同期エンドポイントを使用します。
curl --location 'http://localhost:<port>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "tree"
}'Ngrokを使用する場合のCurl コマンド
curl --location 'http://<your-ngrok-url>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "tree"
}'Cloudflareを使用する場合のCurlコマンド
curl --location 'http://<your-cloudflare-url>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "tree"
}'ファイル入力パラメータ (FILEDATA)
ファイル入力が必要なコマンドでは、filedata フィールドに JSON を渡し、ファイル名として FILEDATA を指定できます。物理ファイルのアップロードを行わずに、REST API を通じてファイルベース処理を実行できます。
FILEDATAの例
PAMプロジェクトのインポート
curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "pam project import --filename=FILEDATA --name=\"My PAM Project\"",
"filedata": {
"project": "My PAM Project",
"pam_data": {
"resources": [
{
"type": "pamDirectory",
"title": "Domain Controller",
"directory_type": "active_directory",
"host": "dc.example.com",
"port": "636",
"use_ssl": true,
"domain_name": "example.com"
}
]
}
}
}'インポートコマンド
curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
"command": "import FILEDATA --format=json",
"filedata": {
"records": [
{
"title": "My Website",
"login": "[email protected]",
"password": "MyPassword123!"
}
]
}
}'FILEDATA の特長
Automatic Processing: 手作業でファイルを扱う必要なし
Temporary File Management: 一時ファイルの作成と削除をサービス側で自動処理
Security: 機密データがログで自動マスクされるため安全
Error Handling: エラー発生時も確実にクリーンアップ
Both API Versions:
/api/v1/executecommandと/api/v2/executecommand-asyncの両方で利用可能
Postman
Postmanアプリからもリクエストを送信できます。Content-Type ヘッダと api-key ヘッダを設定してください。以下は参考画像です。
api/v1 の全レスポンス、および api/v2 の結果取得は共通の基本形式を使用します。
{ "command": "<command_name>", "data": <command_specific_data>, "status": "success" }コマンドごとの応答について
一部のコマンドはJSON形式で見やすく整形されるよう変更されています。その他のコマンドはコマンダー CLIと同じ形式でデータを返します。
整形済み出力の例
list (ls) コマンド
{ "status": "success", "command": "ls", "data": { "folders": [ { "number": 1, "uid": "folder_uid_string", "name": "My Folder", "flags": "RW" } ], "records": [ { "number": 1, "uid": "record_uid_string", "type": "login", "title": "My Login", "description": "Optional description" } ] } }tree コマンド
{ "status": "success", "command": "tree", "data": [ { "level": 0, "name": "Root Folder", "path": "Root Folder" }, { "level": 1, "name": "Subfolder", "path": "Root Folder/Subfolder" } ] }mkdir コマンド
{ "status": "success", "command": "mkdir", "data": { "folder_uid": "new_folder_uid_string" } }record-add コマンド
{ "status": "success", "command": "record-add", "data": { "record_uid": "new_record_uid_string" } }search record コマンド
{ "status": "success", "command": "search record", "data": [ { "number": 1, "uid": "record_uid_string", "type": "login", "title": "Matching Record", "description": "Optional description" } ] }search folder コマンド
{ "status": "success", "command": "search folder", "data": [ { "number": 1, "uid": "folder_uid_string", "name": "Matching Folder" } ] }get コマンド
{ "command": "get", "data": { "attachments": "service_config.yaml 537b ID: XYZ", "last_modified": "2025-01-18 15:35:21", "share_admins": "[email protected]", "shared": "False", "shared_users": "[email protected] (Owner)", "title": "Commander Service Mode", "type": "", "uid": "folder_uid_string" }, "status": "success" }--format=json を有効化したコマンド (例: audit-report --format=json)
{ "status": "success", "command": "audit-report", "data": [ { "audit_event_type": "open_record", "created": "2025-02-18T10:30:45+00:00", "geo_location": "New York, NY, US", "ip_address": "192.168.1.100", "keeper_version": "Commander 16.11.0", "message": "User [email protected] opened record UID ABCD1234EFGH5678", "username": "[email protected]" } ] }最終更新