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-CN.md

相关文档:

API 结果代码指南 (RstVal)