giip
SES案件登録
6分で読了

サーバーAPIリファレンス (v1.5)

GIIPプラットフォームで管理するサーバー資産の情報を照会するためのAPI詳細仕様です。

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

📋 概要

サーバーAPIを活用すると、インベントリに登録されたサーバーの物理的・論理的状態を確認できます。

🔐 認証方式（実装ベース、2026-08-20 giip #1277 実測）

実際に動作が確認できているのは、下記の LsvrDetail（giipApiSk2 汎用SPラッパー経由） です。このラッパーは HTTPヘッダーではなく、POST本文のフィールドのみで認証します。

  • エンドポイント: POST https://giipfaw.azurewebsites.net/api/giipApiSk2
  • Content-Type: application/x-www-form-urlencoded
  • フィールド:
    • text: [コマンド名] [パラメータ名...]
    • token: [Your_SK] — SKは必ずこのフィールドで渡す（textやjsondataにSKを入れない）
    • jsondata: パラメータ値（コマンドごとに形式が異なる — 下記「2. LsvrDetail」参照）
  • ⚠️ giipfaw/giipApiSk2/run.ps1を直接確認した結果（2026-08-20）、このエンドポイントは HTTPヘッダーを一切パースしません。 x-giip-akのようなヘッダーを送っても無視され、Azure Function自体もauthLevel: anonymousのためFunction Key（?code=）も不要です。認証は上記tokenフィールドの値のみで行われます。

⚠️ 旧記載（api.giip.io / x-giip-ak）について

以前この文書に記載されていた https://api.giip.io/v3 ホストと x-giip-ak ヘッダーは、コードベース全体（giipfaw Azure Functions、giipv3 ソース）を検索した結果、実装のどこにも存在しないことを確認しました（0件）。同じ例文が他の複数のAPIガイド文書にもコピーされていたため、テンプレートのプレースホルダーだった可能性が高いです。実運用では使用しないでください。 上記「認証方式」の実装済みエンドポイントを使用してください。

🔍 エンドポイント

サーバー詳細情報の単件取得（LsvrDetail）— 実測検証済み（giip #1277）

  • コマンド: text=LsvrDetail
  • 説明: LSSN（サーバー内部通し番号）1件分の詳細情報を返します。内部的に pApiLSVRDetailbySk(@sk, @lssn bigint, @jsondata=NULL) → pLSvrDescOptbyAT を呼び出します。
  • リクエスト例: 
    POST https://giipfaw.azurewebsites.net/api/giipApiSk2
Content-Type: application/x-www-form-urlencoded

text=LsvrDetail&token={SK}&jsondata=71289
    （71289は照会対象サーバーのLSSN）
  • レスポンス例（lssn=71289）: 
    { "data": [ { "LSsn": 71289, "LSHostname": "shinsema0104", "CSn": 70418, "CGCode": "smtodr-group", "lsRegdt": "2026-...", "LSLastHeartbeat": null } ] }
  • 🚨 jsondataは生の数値文字列のみ（オブジェクトで包むと失敗）:
    • ✅ 成功: jsondata=71289
    • ❌ 失敗: jsondata={"lssn":71289}、{"id":71289}、{"isn":71289} など — どのキーで包んでも Error converting data type nvarchar to bigint エラーになります。
    • 原因: textがLsvrDetailという1語のみ（パラメータ名が続かない）のため、run.ps1はこの呼び出しを「パラメータ名なしの単一コマンド」経路で処理します。この経路ではjsondataから個別キーを取り出す代わりに、jsondata文字列全体をそのままエスケープしてSPの第2引数（@lssn bigint）に文字列リテラルとして追加します（giipApiSk2の自動jsondata付与ロジック、run.ps1内コメントISN 161）。そのリテラルが71289のように数値のみであればSQL Serverがnvarchar→bigintの暗黙変換に成功しますが、{"lssn":71289}のように波括弧が混じると変換できずエラーになります。

🛠️ 活用例（Shellスクリプト、実測動作確認済み）

# LSSN 71289 のサーバー詳細を取得
curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk2" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=LsvrDetail" \
     --data-urlencode "token=YOUR_SK" \
     --data-urlencode "jsondata=71289"

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

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

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

トラブルシューティング

症状原因解決
LsvrDetail 照会で Error converting data type nvarchar to bigint エラーjsondataを{"lssn":71289}のようにオブジェクトで包んでいる — text=LsvrDetailにはパラメータ名がないため、jsondata全体が文字列のまま@lssn bigint引数に代入されるjsondataにLSSNの生の数値のみを渡す（例: jsondata=71289）。オブジェクトで包まない
LsvrDetail 照会で認証が拒否されるPOST本文のtokenフィールドの欠落・誤り、または無効化（再発行/ローテーション）されたSKの使用。x-giip-ak等のヘッダーはこのエンドポイントで一切使用されないため、ヘッダーをいくら設定しても無効です。POST本文のtokenフィールドに有効な（現在発行済みの）SKを含めているか確認します。
LsvrDetail 照会結果が空存在しないLSSNを使用有効なLSSNで再照会します

🚫 動作しないコマンド（giip #1281）

以下のコマンドは giipApiSk2 ディスパッチャに対応する SP が存在しないため動作しません。UI を利用してください。

コマンド原因代替手段
LSVRList <CSN>pApiLSVRListbySk SP が giipdb に存在しないサーバーリストページ を利用してください
LSvrPut '<lsUsage>', <CSN>SK ベースの pApiLSvrPutbySk SP が存在しない（AK ベースの pApiLSvrPutbyAK のみ存在、giipApiSk2 から呼び出し不可）サーバーリストページ を利用してください

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

v1.5 変更履歴（2026-08-20, giip #1281）: LSVRList・LSvrPut を API 詳細から削除し、動作しないコマンド表で UI 代替手段を明記。 v1.4 変更履歴（2026-08-20, giip #1277）: 外部ユーザー（smartorder-works, csn 70418）の実測報告により文書と実装の不一致を発見し修正。 ① LsvrDetail（単一サーバー詳細取得）エンドポイントを新規追加 — 従来この文書には一切記載がなかった（報告の核心的な指摘事項）。 ② 認証方式を訂正: 従来の https://api.giip.io/v3 ホスト + x-giip-ak ヘッダーの記載は、コードベース全体検索の結果、実装のどこにも存在しないことを確認（0件）。実際のホスト・認証方式（POST /api/giipApiSk2、Content-Type: application/x-www-form-urlencoded、token/text/jsondataフィールド、ヘッダー不使用）に置き換え。 ③ jsondataにオブジェクトではなく生の数値のみが許可されるLsvrDetail固有のルールと、その原因（run.ps1の単一パラメータケース + ISN 161 自動jsondata付与ロジック）を実測に基づいて説明。 ④ /server/list・/server/heartbeat・/server/command は対応する実装を今回の調査で確認できず「未検証・レガシー記載」として明記（本Issueの範囲外のためライブテストは未実施）— 後続確認は giip #1281 で追跡。

関連ドキュメント:

関連ガイド

API結果コード (RstVal)tDefRstテーブルに基づいたAPI結果値およびメッセージの標準定義API概要と認証共通レスポンス形式, エラーコード, AK/SK認証Sk3 高性能ロギングAPIエージェントのエラー検知およびデータ整合性検証のためのロギングブリッジ
← PreviousSk3 高性能ロギングAPINext →データベース管理API