システム管理 API リファレンス

サーバーにコマンドを送信したり、エージェントの状態を制御したりするシステムレベルの自動化 API を案内します。

📋 概要

この API モジュールは、GIIP エージェントを通じて個別のサーバーに直接コマンドを発行したり、サーバーのメタデータ（タグなど）を管理したりするためのエンドポイントを提供します。

🔐 認証およびヘッダー

すべてのリクエストは、共通の認証ヘッダーを含める必要があります。

• Header: x-giip-ak: [Your Access Key]
• Header: x-giip-sk: [Your Secret Key]

🚀 主要な API エンドポイント

1. リモートコマンド実行 (Run Remote Command)

• URL: POST /api/system/command/run
• 説明: 指定されたサーバーで特定のシェルスクリプトまたはコマンドを実行します。
• Request Body:

{
  "serverIsn": 456,
  "command": "ls -al /var/log",
  "timeout": 30
}

2. エージェント制御 (Agent Control)

• URL: POST /api/system/agent/control
• 説明: サーバーにインストールされた GIIP エージェントをリモートで再起動したり、設定を同期させたりします。
• Request Body:

{
  "serverIsn": 456,
  "action": "restart"
}

3. サーバータグの管理 (Manage Server Tags)

• URL: POST /api/system/server/tags
• 説明: サーバーを分類するためのタグリストを更新します。
• Request Body:

{
  "serverIsn": 456,
  "tags": ["Production", "Web", "Region-KR"]
}

🔍 レスポンスデータの例 (Command Run)

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "jobId": "JOB-10293",
    "output": "total 1024\ndrwxr-xr-x 2 root root ...",
    "exitCode": 0
  }
}

💡 活用事例

• 自動パッチ管理: 脆弱性が発見されたパッケージに対して、全サーバーに一括アップデートコマンドを送信します。
• 動的リソース割り当て: タグ管理 API を使用して、新しく作成された VM の用途を自動的に指定し、ポリシーを適用します。

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

リモートコマンドの実行（ Run Remote Command ）やエージェント制御のような機密性の高いシステム管理作業において、操作の整合性確保と詳細な実行履歴の追跡のために、 giipApiSk3 エンドポイントを推奨します。

• エンドポイント: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 利点: コマンドの実行失敗時に呼び出し元の詳細な環境情報（IP, UA）と StackTrace を即座に記録し、不正なリクエストやネットワーク障害の状況を迅速かつ明確に把握できるように支援します。
• 活用チップ: jsondata 置換機能を使用して、複雑なシェルコマンド文字列や特殊文字が含まれるタグ情報を送信する際、データを損失することなく安全に管理できます。

🔧 トラブルシューティング

症状	原因	解決
リクエストが認証エラーで拒否される	x-giip-ak / x-giip-sk ヘッダーの欠落または不正なキー	有効なAccess KeyとSecret Keyを両方のヘッダーに含めて再リクエスト
リモートコマンドが実行されない	serverIsn が正しくない、または対象サーバーのエージェントがオフライン	サーバー識別子を確認し、エージェント制御API(action: restart)でエージェントを再起動
レスポンスの RstVal が0以外	コマンド実行の失敗、または timeout の超過	RstMsg と Data.exitCode を確認し、必要に応じて timeout 値を引き上げる
特殊文字を含むタグ送信時にデータが失われる	jsondata 置換機能を未使用	giipApiSk3 エンドポイントの jsondata フィールドで送信し、データ損失を防止

---

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

---

関連ドキュメント:

• API結果コードガイド (RstVal)