Sk3 (高性能ロギングおよび整合性検証) APIガイド

GIIPプラットフォームのエージェント転送エラー検知およびデータ整合性検証のためのHigh-fidelityロギングブリッジAPIである giipApiSk3 の使用方法をご案内します。

📋 概要

giipApiSk3 は、従来の giipApi に強力なロギングおよびデータパース機能を追加した拡張エンドポイントです。エージェントのリクエスト処理中に発生するすべての例外と警告を自動的に tErrorLogs テーブルに詳細に記録し、複雑なJSONデータをSQLパラメータに自動マッピングする機能を提供します。

⚠️ エンドポイントの位置づけ (重要)

giipApiSk3 は デバッグ・High-fidelityロギング検証専用 のエンドポイントであり、Azure Functionレベルで匿名 (Anonymous) 認証を使用します。 エージェントの標準運用エンドポイントは giipApiSk2 です。 本番トラフィックを恒常的にSk3へ切り替えないでください。 Sk3はSk2の処理ロジックに詳細ロギングを追加したコピーであるため、Sk2で正常なリクエストがSk3でのみ失敗する場合、それはSk3のデバッグコードの問題です (この場合Sk2は絶対に修正せず、Sk3のみを点検)。

📡 エンドポイント情報

URL: https://giipfaw.azurewebsites.net/api/giipApiSk3
認証: Azure Functionレベルでは匿名(Anonymous)認証を使用しますが、実際のDB作業時には有効な usertoken (AK) または sk (Secret Key) フィールドをリクエストボディに含める必要があります。

🔐 主要パラメータ

フィールド名	タイプ	説明
`text`	String	実行しようとするコマンド文字列 (例: `LSVRList`, `KVSPut`)
`jsondata`	String	複雑なパラメータを含むJSON文字列
`token` / `sk`	String	認証のための Access Key または Secret Key
`user_id`	String	呼び出すユーザーID
`lssn`	String	セッション/サーバー識別子 (必要な場合)

🚀 主な特徴

1. High-fidelity ロギング

すべてのAPI呼び出し時にクライアントIP、User-Agent、Referer情報を自動的に収集し、エラー発生時はスタックトレースを含む詳細なログを tErrorLogs に記録します。

2. jsondata 自動置換

text パラメータ内のキーワードを jsondata に含まれる値で自動的に置換します。

例:
- text: LSvrPut 'jsondata', 44
- jsondata: {"lsUsage": "Web_Server"}
- 実際の実行クエリ: exec pApiLSvrPutbySk '...', N'Web_Server', 44

3. KVSPut 自動マッピング

text に KVSPut コマンドが含まれている場合、 jsondata の kType, kKey, kFactor, kValue フィールドを自動的に抽出し、 pApiKVSPutbySk プロシージャを呼び出します。

💻 使用例

PowerShell 呼び出し例

$apiUrl = "https://giipfaw.azurewebsites.net/api/giipApiSk3"
$body = @{
    text      = "KVSPut lssn, 1234, netstat"
    jsondata  = @{
        connections = @(
            @{ remote_ip = "10.0.0.10"; state = "ESTABLISHED" }
        )
    } | ConvertTo-Json -Compress
    usertoken = "YOUR_ACCESS_KEY"
}

$resp = Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $body
$resp.data

cURL 呼び出し例

curl -X POST "https://giipfaw.azurewebsites.net/api/giipApiSk3" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "text=ErrorLogList 50" \
     --data-urlencode "usertoken=YOUR_ACCESS_KEY"

🔍 レスポンスデータ構造

成功時は以下のようなJSON構造を返却します。

{
  "data": [
    { ... 結果レコード ... }
  ],
  "debug": {
    "_debug_spName": "ErrorLogList",
    "_debug_executedQuery": "exec pApiErrorLogListbySk '...', 50"
  }
}

トラブルシューティング

症状	原因	解決
すべてのリクエストでHTTP 500が返る	Sk3デバッグ関数の構文・コンパイルエラー（Sk2は正常）	Sk2は絶対に修正せず、`giipApiSk3` 関数コードのみを点検して構文エラーを修正します。
`RstVal 401` または認証拒否が発生する	リクエストボディに `usertoken`(AK) または `sk` フィールドが欠落	匿名認証とは別に、有効な `usertoken`/`sk` をボディに含めます。
`jsondata` の値が実行クエリに反映されない	`text` の置換キーワードと `jsondata` のフィールド名の不一致	`text` の `'jsondata'` 位置と `jsondata` のキー（例: `lsUsage`）が正確に一致するか確認します。
`KVSPut` 呼び出しが無視される、または空の値で保存される	`jsondata` に `kType`/`kKey`/`kFactor`/`kValue` フィールドが欠落	4つのフィールドをすべて含め、`pApiKVSPutbySk` マッピングが完成するようにします。

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

関連ドキュメント:

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

← PreviousAPI概要と認証 Next →インフラ管理API