APIの使用

コマンダーサービスモードにおけるAPI利用

APIバージョン

このサービスでは、キュー設定に基づいて2種類のAPIバージョンを利用できます。

• /api/v2/ – キュー有効 (デフォルト): 非同期処理方式でリクエストが失われません

• /api/v1/ – キュー無効 (v17.1.6以前): 同期方式で直接実行します

v2のキューAPIはコマンダー17.1.7で追加されました (リリース日: 2025年8月28日)。

リクエストキューシステム (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 ヘッダを設定してください。以下は参考画像です。

PostmanにおけるHTTPボディ設定

Postmanでのヘッダ構成

Postmanでv2APIのリクエストとレスポンス構造を確認する方法

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]" } ] }