3分鐘閱讀

Sk3 (高性能日誌與完整性校驗) API 指南

本指南介紹了 GIIP 應用的高保真 (High-fidelity) 日誌橋接 API giipApiSk3 的使用方法，該 API 用於監測助理 (Agent) 傳輸錯誤及校驗數據完整性。

📋 概述

giipApiSk3 是在現有 giipApi 基礎上增加了強大的日誌記錄和數據解析功能的增強型端點。它會自動將助理在請求處理過程中產生的所有異常和警告詳細記錄到 tErrorLogs 表中，並提供將複雜的 JSON 數據自動映射到 SQL 參數的功能。

⚠️ 端點定位 (重要)

giipApiSk3 是除錯·高保真日誌校驗專用端點，在 Azure Function 層級使用匿名 (Anonymous) 認證。 代理的標準生產端點是 giipApiSk2。 請勿將生產流量長期切換到 Sk3。 Sk3 是在 Sk2 處理邏輯基礎上增加詳細日誌的副本，因此若某請求在 Sk2 上正常但僅在 Sk3 上失敗，則說明是 Sk3 除錯程式碼的問題（此時切勿修改 Sk2，僅排查 Sk3）。

📡 端點資訊

URL: https://giipfaw.azurewebsites.net/api/giipApiSk3
認證: Azure Function 級別使用匿名 (Anonymous) 認證，但在進行實際資料庫操作時，必須在請求體中包含有效的 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 資訊；發生錯誤時，會將包含堆棧跟蹤 (StackTrace) 的詳細日誌記錄到 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` 欄位	包含全部四個欄位，使 `pApiKVSPutbySk` 映射得以完成。

版本: 1.0
最後更新: 2026-04-11
源碼: giipv3/public/help/api-sk3.zh-TW.md

相關文檔:

API 結果代碼指南 (RstVal)