Skip to content

API.md

Latest commit

 

History

History
181 lines (153 loc) · 11 KB

API.md

File metadata and controls

181 lines (153 loc) · 11 KB
Raw

AI Notebook Execution Platform 前端 API 說明

API 通用規範

  • 所有 API 路徑皆以 /api/v1/ 為前綴，採用 RESTful 設計。
  • 所有需驗證的 API，Header 必須帶 Authorization: Bearer <JWT Token>。
  • 請求與回應格式皆為 JSON（檔案下載除外，為二進制流）。
  • 錯誤回應格式：{ "errorCode": "string", "message": "string" }，HTTP 狀態碼對應 401/403/500 等。
  • 支援分頁的 API，請帶 page（從0起算）、size 參數。
  • 檔案下載 API 響應需設置 Content-Type: application/octet-stream 及 Content-Disposition。
  • 建議所有請求皆走 HTTPS。

API 一覽表

認證與登入

  • 登入（POST /api/v1/auth/login） • Header: Content-Type: application/json • Body: { username: string, password: string } • Response 200: { accessToken: string }

  • 使用 Access Token • 之後所有需驗證的 API 請求皆在 HTTP Header 加入：

    Authorization: Bearer <accessToken>

  • 登出 • 前端清除本地 Token 並導向登入頁：

    localStorage.removeItem('jwt');
window.location.href = '/login';

任務上傳

方法 路徑 認證 請求格式 請求參數 回應資料 說明
POST /api/v1/task/submit Bearer JWT (User) multipart/form-data - file: .ipynb 檔案
  • gpuRequired: boolean
  • gpuType: string (選填，gpuRequired=true 時)
  • clientInfo: string (前端裝置/瀏覽器資訊 JSON) | 200 { submissionId: string, status: string, queuePosition: number, estimatedWaitTime: number }
    或 4xx/5xx { errorCode: string, message: string, riskScore?: number } | 上傳 Notebook 任務，後端依資源排程執行 | | GET | /api/v1/queue/status | Bearer JWT (User) | { cpuQueueDepth: number, cpuQueueMax: number, gpuQueues: Array<{ type: string; depth: number; max: number }>, estimatedWaitTime: number } | 查詢 CPU 與 各類 GPU 佇列狀態 |

任務狀態

方法 路徑 請求參數 響應數據 說明
GET /api/v1/task/list Query: { page: number, size: number } { tasks: [Task], total: number } 查詢任務列表
GET /api/v1/task/status/{id} Path: id { submissionId: string, status: string, startTime: string, endTime: string, duration: number, ... } 查詢單一任務狀態
POST /api/v1/task/cancel/{id} Path: id { message: string } 取消等待中任務
GET /api/v1/task/result/{id} Path: id 二進制流或 JSON 錯誤 下載任務執行完成的 .ipynb 檔案
POST /api/v1/task/notify/{id} Path: id, Body: { email: string } { message: string } 或 JSON 錯誤 發送結果到指定郵箱

系統公告

方法 路徑 請求參數 響應數據 說明
GET /api/v1/announcements Query: { page: number, size: number } { announcements: [Announcement], total: number } 查詢公告列表

使用時長

方法 路徑 請求參數 響應數據 說明
GET /api/v1/usage/current 無 { totalUsedTime: number, remainingTime: number, periodStart: string, periodEnd: string } 查詢目前使用者時長
GET /api/v1/usage/history Query: { startDate?: string, endDate?: string, page: number, size: number } { records: [UsageRecord], total: number } 查詢時長歷史紀錄

管理員功能

方法 路徑 請求參數 響應數據 說明
POST /api/v1/admin/announcement Body: { title: string, content: string, priority: string, startDate: string, endDate: string } { id: string, message: string } 新增公告
PUT /api/v1/admin/announcement/{id} Path: id, Body: { ... } { message: string } 編輯公告
DELETE /api/v1/admin/announcement/{id} Path: id { message: string } 刪除公告
GET /api/v1/admin/tasks/pending Query: { limit?: number } { tasks: [Task] } 查詢等待中任務
POST /api/v1/admin/task/cancel/{taskId} Path: taskId { message: string } 取消等待中任務
POST /api/v1/admin/queue/clear 無 { message: string } 清空所有等待中任務
POST /api/v1/admin/security/config Body: { riskThreshold: number, promptTemplate: string, fallbackPolicy: string } { message: string } 配置 LLM 安全檢查參數
GET /api/v1/admin/security/status 無 { apiHealth: string, successRate: number, avgResponseTime: number, lastFailure: string } 查詢 LLM API 健康狀態
GET /api/v1/admin/security/report Query: { startDate?: string, endDate?: string, riskLevel?: string, page: number, size: number } { checks: [SecurityCheck], total: number, riskDistribution: object } 查詢 LLM 安全檢查報告
GET /api/v1/admin/report Query: { startDate?: string, endDate?: string, userId?: string, sort?: string, page: number, size: number } { report: object, total: number } 生成使用統計報表
GET /api/v1/admin/users Query: { page: number, size: number, query?: string } { items: [User], total: number } 查詢用戶列表，支援分頁與搜尋
GET /api/v1/admin/users/{userId} Path: userId { userId: string, name: string, email: string, role: string, remainingTime: number, ... } 查詢單一用戶詳情
POST /api/v1/admin/usage/adjust Body: { userId: string, amount: number, reason: string } { message: string } 調整用戶剩餘時長（正數為增加，負數為減少，單位秒）
POST /api/v1/admin/queue/task/{id}/remove Path: id { message: string } 移除單一佇列任務
GET /api/v1/admin/queue/task/{id}/download Path: id 二進制流或 JSON 錯誤 下載指定任務的 notebook 上傳原始檔案（僅管理員可用）
POST /api/v1/admin/security/apikey Body: { apiKey: string, model: string } { message: string } 儲存 LLM API 金鑰與模型
POST /api/v1/admin/security/apikey/test Body: { apiKey: string, model: string } { success: boolean, message?: string } 測試 LLM API 金鑰與模型
GET /api/v1/admin/tasks/{submissionId} Path: submissionId TaskDto JSON 取得單一任務完整詳情，含風險掃描結果（riskMessage）、結果路徑（resultPath）
GET /api/v1/admin/tasks/{submissionId}/download Path: submissionId 二進制 Notebook (.ipynb)流或 JSON 錯誤 下載指定任務執行結果 (.ipynb) 流，檔案來源為 S3，Header: Content-Type: application/octet-stream, Content-Disposition: attachment; filename="result_{submissionId}.ipynb"
GET /api/v1/admin/gpus 無 string[] 取得所有允許的 GPU 類型
POST /api/v1/admin/gpus Body: { type: string } { message: string } 新增 GPU 類型
DELETE /api/v1/admin/gpus/{type} Path: type { message: string } 刪除指定 GPU 類型

用戶管理

方法 路徑 請求參數 響應數據 說明
GET /api/v1/admin/users Query: { page: number, size: number, query?: string } { items: [User], total: number } 查詢用戶列表，支援分頁與搜尋
GET /api/v1/admin/users/{userId} Path: userId { userId: string, name: string, email: string, role: string, remainingTime: number, ... } 查詢單一用戶詳情
POST /api/v1/admin/users Body: { username: string, name: string, email: string, password: string, role: string } { userId: string, message: string } 新增用戶
DELETE /api/v1/admin/users/{userId} Path: userId { message: string } 刪除用戶

主要資料結構

  • Task: 任務物件，包含 submissionId, userId, status, resourceType, vramSize, queuePosition, startTime, endTime, duration, riskScore, riskMessage, ...
  • Announcement: 公告物件，包含 id, title, content, priority, startDate, endDate
  • UsageRecord: 使用時長紀錄，包含 taskId, startTime, endTime, duration, status
  • SecurityCheck: 安全檢查紀錄，包含 submissionId, userId, riskScore, actionTaken, checkedAt

API 狀態/錯誤碼

  • 200: 成功
  • 400: 請求參數錯誤
  • 401: 未授權
  • 403: 權限不足
  • 404: 資源不存在
  • 500: 伺服器錯誤

⚙️ 新增/更新 API 變更紀錄

以下為前端新需求所需後端新增或調整的 API，請協同後端實作：

1. 查詢所有使用者任務（分頁 + 篩選）

  • 方法：GET
  • 路徑：/api/v1/admin/tasks
  • Query 參數（皆可選）：
    • page (int, from 0)
    • size (int)
    • userId (string)
    • submissionId (string)
    • status (string，如 WAITING,SCHEDULED,…)
    • startDate/endDate (YYYY‑MM‑DD)
  • 返回：Page<TaskDto> JSON，主要使用 content 與 totalElements。

2. 單筆任務詳情

  • 方法：GET
  • 路徑：/api/v1/admin/tasks/{submissionId}
  • Path 參數：submissionId (string)
  • 返回：完整 TaskDto，需包含：
    • submissionId,userId,status,createdAt,startTime,endTime,duration
    • riskScore,riskMessage (JSON string), resultPath (S3 物件鍵或 null)

3. 下載執行結果 (.ipynb)

  • 方法：GET
  • 路徑：/api/v1/admin/tasks/{submissionId}/download
  • Path 參數：submissionId
  • 返回：二進制流，Header:
    • Content-Type: application/octet-stream
    • Content-Disposition: attachment; filename="result_{submissionId}.ipynb"
  • 錯誤：403/404 JSON 錯誤格式 { errorCode, message }

4. 下載原始上傳檔（Pending 任務）

  • 方法：GET
  • 路徑：/api/v1/admin/queue/task/{submissionId}/download
  • Path 參數：submissionId
  • 返回：二進制流，Header:
    • Content-Type: application/octet-stream
    • Content-Disposition: attachment; filename="submission_{submissionId}.ipynb"
  • 錯誤：403/404 JSON 錯誤 { errorCode, message }

5. 管理員 GPU 類型管理

  • GET /api/v1/admin/gpus：回傳 string[]，所有目前允許的 GPU 類型
  • POST /api/v1/admin/gpus：Body: { type: string }，新增 GPU 類型，成功後回傳更新後列表
  • DELETE /api/v1/admin/gpus/{type}：Path 參數 type，刪除指定 GPU 類型，成功後回傳更新後列表

權限：上述所有 /api/v1/admin/** 路徑需加上 @PreAuthorize("hasRole('ADMIN')")。
驗證：請後端確保 JWT filter 已攔截並授權。
日誌：推薦記錄下載行為至系統日誌，包含 userId、submissionId、timestamp、status，以供審計。

更新紀錄

  • 2025-04-24：
    • 合併重複 API 區塊，統一格式，補齊所有請求與回應欄位。
    • 新增 clientInfo（裝置、作業系統、瀏覽器）於任務上傳。
    • 移除舊有重複、過時 API 說明。
    • 完善管理員、公告、時長、任務等 API 欄位。
    • 明確所有 API 欄位型別與說明。