giip

API 参考概述 (v1.2)

本指南介绍了用于控制和监控 GIIP 平台微服务及数据库资源的通用 API 规范和认证方式。

📋 概述

GIIP API 遵循 RESTful 架构原则，使用 JSON 格式处理请求并返回响应。为了安全起见，所有 API 只能通过 HTTPS 协议访问，并且必须使用有效的 Access Key 和 Secret Key 才能正常调用功能。

🔐 认证 (Authentication)

所有 API 请求标头中必须包含以下认证信息。

标头键 (Header Key)描述
x-giip-ak从 GIIP 管理员处获取的 Access Key
x-giip-sk从 GIIP 管理员处获取的 Secret Key

[!IMPORTANT] Secret Key 不得泄露给外部，应在服务器端安全管理，以避免直接在客户端 JavaScript (JS) 代码中暴露。

📡 通用响应格式 (Response Format)

GIIP 的所有 API 提供一致的响应格式，以便于客户端处理。

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": { ... }
}
  • RstVal: 成功状态 (0: 成功，其他: 错误)
  • RstMsg: 成功消息 (发生错误时包含详细原因说明)
  • Data: 请求成功时返回的数据主体

🚀 请求格式

所有 API 请求均遵循 Azure Function 调用规范，以 

application/x-www-form-urlencoded
方式进行 POST。

主要表单数据

字段说明
text要执行的命令字符串
user_id调用者用户 ID
token会话令牌
usertoken用于实际集成的会话令牌

🚀 API 分组指南

有关各领域的详细 API 规范，请参考以下各别指南。

  1. 服务器管理 API：基础设施资产查询与命令执行
  2. 数据库 API：数据库性能与查询统计
  3. 问题管理 API：故障告警与状态更新
  4. 费用分析 API：云端使用量与费用预测
  5. 项目/用户 API：权限与组织管理
  6. 监控数据查询 API：实时 CPU/MEM/Disk 指标、性能历史记录及进程列表
  7. 网络安全策略 API：防火墙规则查询、IP 允许/阻止及策略批量部署
  8. 网络拓扑 (Net3D) API：基础设施连接数据收集与传输规范 (netinv, netstat, db_connections)
  9. 系统管理 API：远程命令执行、助理 (Agent) 控制及服务器标签管理
  10. KVS (键值存储) API：Factor 数据查询 (KVSFactorLast, KVSFactorList)
  11. Vercel 管理 API：Vercel 配置管理及部署历史查询
  12. GitHub Actions 管理 API：GitHub 仓库集成及工作流历史查询
  13. 邮件服务器管理 API：SMTP 服务器配置及测试发送 (仅限管理员)
  14. Sk3 (高性能日志) API：用于助理传输错误检测和数据完整性校验的高保真日志桥接器
  15. 公共响应值与结果代码指南 (RstVal)：基于 tDefRst 表的标准结果代码说明

🛠️ 通用错误代码

  • 401 Unauthorized：认证信息无效或已过期
  • 403 Forbidden：无权调用该 API（包括基于 IP 的访问控制）
  • 429 Too Many Requests：请求频率超过限制 (Rate Limit)
  • 500 Internal Server Error：服务器内部错误或发生临时故障

📖 开发者注意事项

  • 端点调用模块：
    src/lib/lsvrUtils.ts
  • 会话管理：参考 
    sessionStorage
    中的 
    user_id
    , 
    token
    , 
    csn
    , 
    cname
    等
  • 所有集成均默认使用 HTTPS。

🔧 故障排除

症状原因解决方法
返回 401 UnauthorizedAccess Key/Secret Key 已过期或无效重新核对 
x-giip-ak
/
x-giip-sk
请求头的值，必要时请管理员重新发放密钥
返回 403 Forbidden无权调用该 API，或被基于 IP 的访问控制拦截确认账号权限及来源 IP 是否被允许
RstVal
不为 0 但不清楚原因		未查阅标准结果代码的含义检查 
RstMsg
并在 API 结果代码指南 中查询对应代码
请求未被处理或 
text
命令被忽略		请求非 
application/x-www-form-urlencoded
格式，或缺少 
text
/
user_id
/
token
字段		按规范以正确格式发送包含必填字段的表单数据

版本: 1.2 最后更新: 2026-04-11 Markdown 源码: giipv3/public/help/api-reference.zh-CN.md

← Previous
API 结果代码 (RstVal)
Next →
Sk3 高性能日志 API