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

相關文檔:

API 結果代碼指南 (RstVal)