學生名冊 Roster

本物件現階段為選用功能，未來主要將應用於 IDP 文件處理流程中。現階段開發時請預留相關功能的擴充能力。未來規格可能有較大的變化，詳見未來規劃。

在提交考卷作答時，若需對學生提交的唯一性進行識別，可以將學生去識別化的參照字串使用 student_ref 參數傳送。批閱平台將協助識別學生作答的唯一性，並儲存與回傳該參照。

若要對學生去識別的參照字串進行管理，則可以使用學生名冊（Roster）進行。在學生名冊中的每一筆學生資料，均可包含一個 student_ref 與選填的 name（未來將用於 IDP 的手寫姓名辨識流程中）。

{
  "name": "2026 春季 - 七年級",
  "entries": [
    { "student_ref": "student_0041", "name": "王小明" },
    { "student_ref": "student_0042", "name": "陳美玲" },
    { "student_ref": "student_0043" }
  ]
}

entries 為必填，可以是空陣列。每筆均需要 student_ref，在同一份名冊內唯一；name 為選填。一份名冊最多 1,000 筆。

在提交時指定學生的來源名冊

若要對應名冊要發揮作用，需要在建立提交時指定 roster_id 與 student_ref：

{
  "exam_id": "exam_kQXzTR",
  "student_ref": "student_0042",
  "roster_id": "ros_7hK2Qn",
  "responses": ["…"]
}

批次提交的每筆項目也接受同一個欄位。

名冊不是建立提交的必要條件。就算不指定 roster_id，提交亦可正常建立。

更新名冊

名冊可使用 PATCH /rosters/{id} 進行更新。對名冊的更新，請送出調整後的完整名單。修改將立即生效，updated_at 隨之更新。名冊的更新不會產生新版本。

刪除名冊

名冊可使用 DELETE /rosters/{id} 端點刪除。正常刪除將回應 204 狀態。既有提交上的 roster_id 與 student_ref 將持續保留但無法反向解析，且不改變任何既有分數。

在提交時指定學生的來源名冊

更新名冊

刪除名冊

相關

本頁內容