4分钟阅读

项目与用户管理 API 参考

引导您如何通过编程方式查询项目信息并管理 GIIP 平台内的用户权限。

🔌 前往项目列表功能页 → · 👥 前往用户列表功能页 →

📋 概述

此 API 模块提供了对接 GIIP 系统逻辑管理单元——项目 (Project) 以及可访问该项目的用户 (User) 信息的控制功能。

🔐 认证与请求头

所有请求必须包含通用的认证请求头。

Header: x-giip-ak: [Your Access Key]
Header: x-giip-sk: [Your Secret Key]

🚀 核心 API 端点

1. 查询项目列表 (Get Project List)

URL: POST /api/project/list
描述: 返回当前账号 (CSN) 下可访问的所有项目列表。
请求体 (Request Body):

{
  "searchKeyword": ""
}

2. 查询项目详情 (Get Project Detail)

URL: POST /api/project/detail
描述: 查询特定项目的详细设置及已分配的资产数量。
请求体 (Request Body):

{
  "projectIsn": 123
}

3. 查询项目用户列表 (Get Project Users)

URL: POST /api/project/users
描述: 查询分配至特定项目的用户列表及其各自的权限等级。
请求体 (Request Body):

{
  "projectIsn": 123
}

🔍 响应数据示例

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": [
    {
      "projectIsn": 123,
      "projectName": "Mobile App Backend",
      "userCount": 5,
      "serverCount": 12,
      "dbCount": 2
    }
  ]
}

💡 使用场景

CI/CD 流水线: 在部署前通过 API 获取目标项目的服务器列表，以触发并行的包更新。
权限审计: 定期导出各项目的用户权限列表，用于编写安全报告。

4. 项目用户管理（giipapi 命令）

以下是查询、邀请、变更权限、移除项目（CSN）成员时实际使用的 giipapi text/jsondata 命令（参见 giipapi_rules.md）。Web UI 请参见用户列表指南。

查询项目用户列表 (UserList)

命令: text=UserList csn
jsondata: {"csn": 44}
说明: 返回调用者所属项目 (csn) 的成员列表。若调用者不是该项目成员，则无错误地返回空列表 (0 条)。
返回字段: usn, uloginid, uname, uemail, uregdt, isPay, uPerCorp（权限：1=Member，49=Owner）

邀请/映射用户 (PrjUserMap)

命令: text=PrjUserMap csn uloginid
jsondata: {"csn": 44, "uloginid": "user@example.com"}
说明: 将已有的 GIIP 账号（uloginid=登录ID，通常为邮箱）映射为该项目的成员。新成员权限始终从 1（Member）开始。
⚠️ 注意: 若 uloginid 对应的 GIIP 账号尚不存在，映射会失败（retcode 304）。userlist 页面的"邀请"按钮会同时调用此 API 并发送邀请邮件，但界面上会忽略此 API 的失败——若受邀者尚未注册，则只会发送邮件，实际成员映射需等受邀者注册后再次调用此 API 才能完成。
返回: retcode — 200（成功）、201（未认证）、301（调用者不是该 csn 的成员）、304（目标账号不存在）、305（已是成员）

变更用户权限 (PrjUserPer)

命令: text=PrjUserPer csn uloginid uper
jsondata: {"csn": 44, "uloginid": "user@example.com", "uper": 49}
说明: 将成员权限在 Member (1) ↔ Owner (49) 之间变更。调用者必须是该项目的 Owner (49)，且不能通过此 API 变更自己的权限。
uper 允许值: 仅允许 1（Member）或 49（Owner），其他值将被拒绝。
返回: RstVal/RstMsg — 200（成功）、401（未认证）、403（权限不足/非Owner/目标为自身/不允许的uper值）、404（目标不存在或非成员）

移除用户 (PrjUserDel)

命令: text=PrjUserDel csn uloginid
jsondata: {"csn": 44, "uloginid": "user@example.com"}
说明: 删除用户的项目成员身份。删除后该用户将立即失去对该项目所有资产的访问权限。
返回: RstVal/RstMsg — 200（成功）、201（未认证）、301（调用者不是该 csn 的成员）、304（目标不是该项目成员）

🛡️ 巧用 Sk3 (高性能日志)

在进行新增项目注册或修改服务组等影响基础设施整体架构的管理操作时，为了确保操作的一致性并获取详细的审计日志 (Audit Log)，建议使用 giipApiSk3 端点。

端点: https://giipfaw.azurewebsites.net/api/giipApiSk3
优势: 若项目创建失败，系统会立即记录调用者的详细环境信息 (IP, UA) 和堆栈追踪 (StackTrace)，助力快速分析配置错误或权限问题。
使用技巧: 灵活运用 text 命令和 jsondata 的参数替换功能，确保复杂的服务器组说明或非英语名称等信息能完整、安全地得到管理。

🔧 故障排除

症状	原因	解决方法
请求因认证错误被拒绝	缺少通用认证请求头（`x-giip-ak`/`x-giip-sk`）	确认每个请求都包含两个认证请求头
`PrjPut` 调用失败或项目未创建	`text` 命令签名（`PrjPut <cCode>, '<cName>'`）不正确	使用唯一的 `cCode` 和用引号包裹的 `cName`，按准确格式重新调用
`PrjDel` 响应中的 `RstVal` 不为 0	指定了错误的 CSN，或删除权限不足	核对正确的 CSN，并确认拥有删除项目所需的管理员权限
`PrjGrpPut` 的中文/特殊字符名称出现乱码	`text` 字符串中的特殊字符未转义	在 `giipApiSk3` 上使用 `jsondata` 参数替换功能，以无损方式传输名称
调用 `PrjUserMap` 后用户仍未出现在列表中	目标 `uloginid` 的 GIIP 账号尚不存在，映射失败（仅发送了邀请邮件）	让目标用户先注册 GIIP，然后再次调用 `PrjUserMap`
调用 `PrjUserPer` 被拒绝并返回 `403`	调用者不是该项目的 Owner (49)，或目标是调用者自己	使用 Owner 账号调用，且目标应为自己以外的其他成员

版本: 1.2 最后更新: 2026-07-26 源文件: giipv3/public/help/api-project-user.zh-CN.md

相关文档:

API 结果代码指南 (RstVal)