7分で読了

APIリファレンス概要 (v1.2)

GIIPプラットフォームのマイクロサービスおよびデータベースリソースを制御・監視するための共通API規格と認証方式をご案内します。

📋 概要

GIIP APIはRESTfulアーキテクチャの原則に従い、JSON形式を使用してリクエストを処理し、レスポンスを返します。すべてのAPIはセキュリティのためHTTPSプロトコルを通じてのみアクセス可能であり、有効なAccess KeyとSecret Keyを使用することで正常な機能呼び出しが可能になります。

🔐 認証 (Authentication)

すべてのAPIリクエストヘッダーには、以下の認証情報が含まれている必要があります。

Header Key	Description
x-giip-ak	GIIP管理者から発行された Access Key
x-giip-sk	GIIP管理者から発行された Secret Key

[!IMPORTANT] Secret Keyは外部に漏洩してはならず、クライアント側のJavaScript (JS) コードなどに直接露出しないよう、サーバー側で安全に管理する必要があります。

AK/SKの共通用語定義

GIIP全体で使われる認証情報は、実体としては次の3種類に整理できます(2026-08-20、イシュー・タスクAPIでのコード確認+ライブ実測に基づく)。

種類	実体(テーブル/カラム)	発行単位	権限範囲
プロジェクトSK	`tSecretKey.SKey`	プロジェクト(csn)ごと	そのcsnのみ。呼び出し者個人は特定されない共有鍵
ユーザー固定キー	`tCorpUser.uSecretKey`	ユーザー(usn)ごと	そのユーザー本人の所属csn(管理者権限があれば全csn)
ログインセッションAK	`tUserLogin.AccToken`	ログインごとに新規発行、24時間で失効	ログインユーザー本人と同一権限

⚠️ エンドポイントごとに実際のヘッダー名・渡し方が異なります。 上表のx-giip-ak/x-giip-skヘッダーは API群によって使われる一般的な規約ですが、イシュー管理API(/api/giipIssues, /api/giipIssueComments)と CatQuest APIはx-api-keyヘッダー1本(またはAuthorization: Bearer)にAK/SKいずれかをまとめて渡す方式 で、x-giip-ak/x-giip-skという個別ヘッダー名は使いません(実測確認、2026-08-20)。実際に呼び出す前に、必ずそのAPI固有のドキュメント(イシュー・タスクAPI、CatQuest データ API など)でヘッダー名と渡し方を確認してください。本ページの表は「GIIP共通の認証情報の種類」を示すもので、「すべてのAPIが同一のヘッダー名を使う」という意味ではありません。

📡 共通レスポンス形式 (Response Format)

GIIPのすべてのAPIは、一貫したレスポンス形式を提供し、クライアント側の処理を容易にします。

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": { ... }
}

RstVal: 成功の有無 (0: 成功, その他: エラー)
RstMsg: 成功メッセージ (エラー発生時は詳細な原因テキストを含む)
Data: リクエスト成功時に返されるデータ本文

🚀 リクエスト形式

すべてのAPIリクエストは、Azure Function呼び出し規格に従い、application/x-www-form-urlencodedでPOSTします。

主要なフォームデータ

フィールド	説明
text	実行するコマンド文字列
user_id	呼び出し元のユーザーID
token	セッショントークン
usertoken	実際の連動に使用されるセッショントークン

🚀 APIグループ別ガイド

分野別の詳細なAPI仕様については、以下の個別ガイドを参照してください。

サーバー管理API: インフラ資産の照会およびコマンド実行
データベースAPI: DBパフォーマンスおよびクエリ統計
イシュー管理API: 障害アラームおよびステータス更新
コスト分析API: クラウド使用量およびコスト予測
プロジェクト/ユーザーAPI: 権限および組織管理
モニタリングデータ照会API: リアルタイムCPU/MEM/Diskメトリクス、パフォーマンス履歴、プロセスリスト
ネットワークセキュリティポリシーAPI: ファイアウォールルールの照会、IP許可/遮断、ポリシーの一括適用
ネットワークトポロジー(Net3D)API: インフラ接続データの収集・転送規格 (netinv, netstat, db_connections)
システム管理API: リモートコマンド実行、エージェント制御、サーバータグ管理
KVS(キー・バリュー形式)API: factorデータ照会 (KVSFactorLast, KVSFactorList)
Vercel管理API: Vercel設定管理およびデプロイ履歴の照会
GitHub Actions管理API: GitHubリポジトリ連携およびワークフロー履歴の照会
メールサーバー管理API: SMTPサーバーの設定およびテスト送信 (管理者専用)
Sk3 (高性能ロギング) API: エージェント転送エラーの検知およびデータ整合性検証のためのHigh-fidelityロギングブリッジ
共通レスポンスおよび結果コードガイド (RstVal): tDefRstテーブルに基づいた標準結果コードの案内

🛠️ 共通エラーコード

401 Unauthorized: 認証情報が無効か期限切れの場合
403 Forbidden: 当該APIを呼び出す権限がない場合（IPベースのアクセス制御を含む）
429 Too Many Requests: リクエスト頻度制限(Rate Limit)を超過した場合
500 Internal Server Error: サーバー内部エラーおよび一時的な障害が発生した場合

📖 開発者の注意事項

エンドポイント呼び出し部: src/lib/lsvrUtils.ts
セッション管理: sessionStorageの user_id、token、csn、cnameなどを参照
すべての連携はHTTPSを基本とします。

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

症状	原因	解決方法
401 Unauthorized が返される	Access Key/Secret Key が期限切れか無効である	`x-giip-ak`/`x-giip-sk` ヘッダーの値を再確認し、必要に応じて管理者にキーの再発行を依頼します
403 Forbidden が返される	当該 API の呼び出し権限がない、または IP ベースのアクセス制御でブロックされている	アカウント権限と送信元 IP が許可されているかを確認します
`RstVal` が0以外だが原因が分からない	標準結果コードの意味を確認していない	`RstMsg` を確認し、API結果コードガイドで該当コードを照会します
リクエストが処理されない、または `text` コマンドが無視される	リクエストが `application/x-www-form-urlencoded` 形式でない、または `text`/`user_id`/`token` フィールドが欠落している	規格に従い、必須フィールドを含むフォームデータを正しい形式で送信します

関連ドキュメント:

バージョン: 1.3 最終更新日: 2026-08-20 マークダウン原文: giipv3/public/help/api-reference.ja.md

v1.3 変更履歴 (2026-08-20, giip #1280): 「AK/SKの共通用語定義」節を追加し、プロジェクトSK/ユーザー固定キー/ログインセッションAKの3種類を発行元テーブル単位で整理。イシュー管理API・CatQuest APIは本ページの x-giip-ak/x-giip-skヘッダー規約ではなくx-api-keyヘッダー1本を使うことを明記し、実際のヘッダー名は各APIの個別ドキュメントで確認するよう案内(3文書間の齟齬解消)。