5分钟阅读

服务器 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
- 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（服务器内部编号）查询的单条服务器详情。内部调用 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（后面没有参数名），run.ps1 会将此调用当作"无参数名的单一命令"路径处理。该路径不会从 jsondata 中提取单个键值，而是把 jsondata 字符串整体转义后，作为字符串字面量直接追加为 SP 的第二个位置参数（@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` 参数	仅传递 LSSN 的原始数字（如 `jsondata=71289`），不要用对象包裹
`LsvrDetail` 查询时认证被拒绝	POST 正文中 `token` 字段缺失/错误，或使用了已失效（重新签发/轮换）的 SK。`x-giip-ak` 等请求头在此端点完全不起作用，无论如何设置都无效。	确认 POST 正文的 `token` 字段包含当前有效的 SK。
`LsvrDetail` 查询结果为空	使用了不存在的 LSSN	使用有效的 LSSN 重新查询

🚫 不可用命令（giip #1281）

以下命令在 giipApiSk2 调度器中没有对应 SP，无法使用。请使用 UI 替代。

命令	原因	替代方案
`LSVRList <CSN>`	giipdb 中不存在 `pApiLSVRListbySk` SP	请使用服务器列表页面
`LSvrPut '<lsUsage>', <CSN>`	不存在 SK 版本的 `pApiLSvrPutbySk` SP（仅存在 AK 版本的 `pApiLSvrPutbyAK`，无法通过 giipApiSk2 调用）	请使用服务器列表页面

版本: 1.5 最后更新: 2026-08-20 源文件: giipv3/public/help/api-server.zh-CN.md

v1.5 变更历史（2026-08-20, giip #1281）：从 API 详情中删除了不可用的 LSVRList 和 LSvrPut，添加了"不可用命令"表并注明 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 字段，不使用请求头认证）。 ③ 基于实测说明了 LsvrDetail 特有的规则——jsondata 必须是原始数字而非对象，以及其根本原因（run.ps1 的单参数处理路径 + ISN 161 自动 jsondata 追加逻辑）。 ④ /server/list、/server/heartbeat、/server/command 因本次调查未能确认对应实现，标记为"未验证 / 旧文档遗留"（实时测试超出本 Issue 范围）— 后续追踪见 giip #1281。

相关文档:

API 结果代码指南 (RstVal)