giip

サーバーAPIリファレンス

GIIPプラットフォームで管理するサーバー資産の情報を照会し、制御コマンドを伝達するためのAPI詳細仕様です。

🔌 サーバーリスト機能ページへ →

📋 概要

サーバーAPIを活用すると、インベントリに登録されたサーバーの物理的・論理的状態を確認し、エージェントを通じてリモートでコマンドを実行したりサービスを再起動したりすることができます。

🔍 主要なエンドポイント

1. サーバー一覧の照会

プロジェクトまたは顧客単位で登録されたすべてのサーバー情報を取得します。

  • URL: GET /server/list
  • 主なパラメータ:
    • prj_isn (Integer): 特定プロジェクト所属のサーバーのみ照会
    • status (String): Running 、 Stop 、 Unknown などのステータスでフィルタリング
  • レスポンスデータ: ホスト名、IPアドレス、OSタイプ、CPU/メモリ仕様など

2. ハートビートおよびリアルタイム状態の照会

サーバーにインストールされたエージェントの生存信号およびリアルタイムの負荷情報を確認します。

  • URL: GET /server/heartbeat
  • 必須パラメータ: server_isn (サーバー固有番号)
  • レスポンスデータ: 最終受信時刻、現在のCPU使用率、空きメモリなど

3. リモートコマンド実行 (execCommand)

特定のサーバーにシェルコマンドを伝達し、結果を非同期的に受信します。

  • URL: POST /server/command
  • ペイロード:
    • server_isn: 対象サーバー番号
    • command: 実行するコマンド（例: systemctl restart nginx ）
  • レスポンス: コマンド受付ID（ cmd_isn ）を返却（実行結果は /server/command/result で照会）

🛠️ 活用例 (Shellスクリプト)

# 特定サーバーの現在のCPU使用率を確認
curl -X GET "https://api.giip.io/v3/server/heartbeat?server_isn=123" \
     -H "x-giip-ak: YOUR_AK"

🛡️ Sk3（高性能ロギング）の活用

新規サーバーの登録や詳細情報の変更など、インフラ資産管理の核心的な作業において、作業の整合性確保と詳細な監視ログ（Audit Log）のために giipApiSk3 エンドポイントを推奨します。

  • エンドポイント: https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 利点: サーバー登録失敗時に呼び出し元の詳細な環境情報（IP, UA）と StackTrace を即座に記録し、エージェント連動の問題や設定エラーを迅速に分析できます。
  • 活用チップ: text コマンドと jsondata のパラメータ置换機能を活用して、サーバーの用途や複雑な設定値を損失なく安定してプラットフォームに反映させてください。

トラブルシューティング

症状原因解決
サーバー一覧/ハートビート照会で認証エラーが発生するx-giip-ak ヘッダーの欠落または無効有効なAKをリクエストヘッダーに含めているか確認します。
GET /server/list が空のリストを返すprj_isn フィルタの誤り、または status フィルタが厳しすぎるprj_isn の値を確認し、status フィルタ（例: Running）を緩和します。
GET /server/heartbeat がデータを返さないserver_isn の誤り、またはエージェント未受信有効な server_isn を使用し、対象サーバーのエージェント動作を確認します。
リモートコマンド実行後に結果がすぐ返らないexecCommand は非同期で受付ID（cmd_isn）のみ返却返却された cmd_isn で /server/command/result を照会し結果を取得します。

バージョン: 1.1 最終更新日: 2026-04-11 ソースファイル: giipv3/public/help/api-server.ja.md

関連ドキュメント:

← PreviousSk3 高性能ロギングAPINext →データベース管理API