HiTeach API

國際站點 API : https://www.teammodel.net

中國站點 API : https://www.teammodel.cn

API列表

IdToken參數傳遞及驗證
取得老師個人相關數據
取得老師所在學校相關數據
取得學生名單
開始課堂
取得試卷
取得試題
取得課綱
上傳評測結果
取得知識點
錯誤碼
HiTeach Blob相關操作

IdToken參數傳遞及驗證

所有API都需將IdToken置於HEADER提供身分識別及驗證 (特別標註者除外)

HEADER :

X-Auth-IdToken : {IdToken}

取得老師個人相關數據

{POST} {Domain}/hiteach/get-teacher-info

無須傳遞參數

成功返回

{ 
  blob_uri:"XXXXXXXXXXXX", (老師Blob網址)
  blob_sas:"XXXXXXXXXXXX", (老師Blob金鑰，讀+列+寫)
  schools:[  (老師加入的學校清單)
        {
            "schoolId": "hbcn",  (學校簡碼)
            "name": "玉山學校",  (學校名稱)
            "status": "join"  (加入狀態 "invite":邀請 "invite":學校邀請 "request":老師申請 "join":"成為學校老師")
        }
  ],
  defaultschool: "hbcn", (預設學校簡碼)
  courses:[  (老師的個人課程)
        {
            "id": "course123456", (課程ID)
            "name": "個人課程001", (課程名稱)
            "scope": "private",  (課程個人/學校屬性  "school":學校 "private":個人)
            "classes": [  (此課程的班級列表)
                {
                    "code": "Class-hbcn", (班級分區鍵)
                    "id": "個人課程001",  (班級ID)
                    "name": "一年级一班", (班級名稱)
                    "teacher": {  (班主任資訊)
                        "id": "abcd",
                        "name": "小明"
                    },
                    "stuListId": "shiftp01-d164-4fac-8134-4c007d729f0c",  (跑班課學生名單ID)
                    "stuCnt": 4,  (班級學生數)
                    "grpCnt": 0,  (班級分組數)
                    "gradeId": null,  (年級ID)
                    "year": 0, (學年 ※2021-6-1追加) 
                    "scope": "private"  (班級個人/學校屬性  "school":學校 "private":個人)
                }
            ]
        }
  ],
  "exams": [
        {
            "code": "Exam-1595321354",  (評測分區鍵)
            "id": "38d82c17-6aec-4583-a535-d09c1388ba53",  (評測ID)
            "name": "20210205-多元题型范例v2",  (評測名稱)
            "createTime": 1617001064661,  (創建時間)
            "startTime": 1617001064661,  (開始時間)
            "endTime": 1617001064661,  (結束時間)
            "year": 2021,  (學年)
            "source": "1",  (評測來源 0:线上评量 1:课中评量 2:阅卷评量)
            "type": "normal",  (測試類別 [String] regular: 正规考 simulation:模拟考 normal:普通考)
            "progress": "going",  (評測進行狀態 [String] 未發布:pending  進行中:going  完成:finish )
            "stuCount": 21,  (學生總數)
            "scope": "school",  (評測屬性  評測對象為校本班級：school  評測對象為私人課程：private)
            "owner": "teacher",  (評測類型  校園評測：school  個人評測：teacher)
            "period": {  (學段)
                "id": "127e71a7-0ca8-82b8-476b-5269b78066f7",
                "name": "玉山國中"
            },
            "grades": [  (年級)
                {
                    "id": "1",
                    "name": "七年级"
                }
            ],
            "subjects": [  (科目)
                {
                    "id": "c5f96ea0-e65c-f15c-dc59-410da564c185",
                    "name": "數學",
                    "classCount": 0
                }
            ],
            "classes": [  (教室)
                "10de957b-9d11-e3af-9c70-5cbef19eb611",
                "f21b6d72-1466-abbd-8ee6-b754c99b8b33"
            ],
            "papers": [  (試卷)
                {
                    "id": "7074bfb7-564d-f4ce-e142-1662880a41fd",
                    "code": "Paper-hbgl",
                    "name": "109指考-數學甲",
                    "blob": "/exam/71b335aa-a24c-49d3-ba40-319b65972c14/paper/c5f96ea0-e65c-f15c-dc59-410da564c185",
                    "scope": "school",
                } 
            ]
        }
  ]
}

取得老師所在學校相關數據

{POST} {Domain}/hiteach/get-school-info

成功返回

{ 
  blob_uri:"XXXXXXXXXXXX", (學校Blob網址)
  blob_sas:"XXXXXXXXXXXX", (學校Blob金鑰，讀+列)
  blob_sas_read:"XXXXXXXXXXXX", (學校Blob金鑰，讀)
  blob_sas_write:"XXXXXXXXXXXX", (學校Blob金鑰，寫)
  periods: [  (學段資訊)  
        {
            "id": "463db08d-cbe7-48a0-a81a-fc39b3c1fep1",  (學段ID)
            "name": "小學"  (學段名稱)
        }
  ],
  grades: [  (年級資訊)  
        {
            "id": "1379ac00-ccaf-4bb4-9dae-1fccb0031421",  (年級ID)
            "name": "一年級",  (年級名稱)
            "periodId": "463db08d-cbe7-48a0-a81a-fc39b3c1fep1"  (學段ID)
        }
  ],
  subjects: [  (科目資訊)  
        {
            "id": "8b94c6b6-2572-41e5-89b9-a82fcf13891e",  (科目ID)
            "name": "語文",  (科目名稱)
            "periodId": "1"  (學段ID)
        }
  ]
  courses:[  (老師的學校課程)
        {
            "id": "Language101", (課程ID)
            "name": "一年級語文", (課程名稱)
            "scope": "school",  (課程個人/學校屬性  "school":學校 "private":個人)
            "classes": [  (此課程的班級列表)
                {
                    "code": "Class-hbcn", (班級分區鍵)
                    "id": "Class0101",  (班級ID)
                    "name": "一年級", (班級名稱)
                    "teacher": {  (班主任資訊)
                        "id": "abcd",
                        "name": "小明"
                    },
                    "stuListId": "35f4a79c-1407-2dad-d851-61c937f5482e",  (跑班課學生名單ID 無時為null)  ※無跑班課學生名單ID時(1)若有班級ID，表示學生為此班級的固定成員(2)若無班級ID表示尚未分配班級學生
                    "stuCnt": 33,  (班級學生數)
                    "grpCnt": 4,   (班級分組數)
                    "gradeId": null,  (年級ID ※2021-6-9 班級廢除年級ID，此欄位為null)
                    "year": 2020, (學年 ※2021-6-1追加) 
                    "scope": "school",  (班級個人/學校屬性  "school":學校 "private":個人)
                }
            ],
            "subject": {
                "id": "9597fb41-2eb1-4b01-9dfb-79438f0d12d6",
                "name": "英語"
            }
        }
  ],
  "exams": [
        {
            "code": "Exam-1595321354",  (評測分區鍵)
            "id": "38d82c17-6aec-4583-a535-d09c1388ba53",  (評測ID)
            "name": "20210205-多元题型范例v2",  (評測名稱)
            "createTime": 1617001064661,  (創建時間)
            "startTime": 1617001064661,  (開始時間)
            "endTime": 1617001064661,  (結束時間)
            "year": 2021,  (學年)
            "source": "1",  (評測來源 0:线上评量 1:课中评量 2:阅卷评量)
            "type": "normal",  (測試類別 [String] regular: 正规考 simulation:模拟考 normal:普通考)
            "progress": "going",  (評測進行狀態 [String] 未發布:pending  進行中:going  完成:finish )
            "stuCount": 21,  (學生總數)
            "scope": "school",  (評測屬性  評測對象為校本班級：school  評測對象為私人課程：private)
            "owner": "teacher",  (評測類型  校園評測：school  個人評測：teacher)
            "period": {  (學段)
                "id": "127e71a7-0ca8-82b8-476b-5269b78066f7",
                "name": "玉山國中"
            },
            "grades": [  (年級)
                {
                    "id": "1",
                    "name": "七年级"
                }
            ],
            "subjects": [  (科目)
                {
                    "id": "c5f96ea0-e65c-f15c-dc59-410da564c185",
                    "name": "數學",
                    "classCount": 0
                }
            ],
            "classes": [  (班級)
                "10de957b-9d11-e3af-9c70-5cbef19eb611",
                "f21b6d72-1466-abbd-8ee6-b754c99b8b33"
            ],
            "finishClasses": [  (已完成的班級) [2021-7-14追加]
                "10de957b-9d11-e3af-9c70-5cbef19eb611"
            ],
            "papers": [  (試卷)
                {
                    "id": "7074bfb7-564d-f4ce-e142-1662880a41fd",
                    "code": "Paper-hbgl",
                    "name": "109指考-數學甲",
                    "blob": "/exam/71b335aa-a24c-49d3-ba40-319b65972c14/paper/c5f96ea0-e65c-f15c-dc59-410da564c185",
                    "scope": "school",
                } 
            ]
        }
  ]
}

錯誤返回

{ 
  error = 1, message = "學校無此老師"  
}

取得班級學生名單，支持學校或老師個人

{POST} {Domain}/hiteach/get-students-list

成功返回

{ 
  students:[  (學生列表)  
        {
            "id": "24904",
            "name": "黄安俐",
            "no": "1",
            "schoolId": "hbcn",
            "groupId": "A",
            "groupName": "A組"
        }
  ]
}

錯誤返回

{ 
  error = 1, message = "學校無此班級"  
}

開始課堂

{Header}

{POST} {Domain}/hiteach/start-lesson

成功返回

{ 
  lesson_code:"XXXXXXXXXXXX", (授課ID ※雪花ID)  
}

處理概要

• 若未傳遞lesson_id、可取得id_token，則生成授課ID，建立綁定資料後返回值
• 若lesson_id、id_token皆可取得，則更新綁定資料後返回值
• 若lesson_id、id_token皆無法取得，則不記入DB，生成授課ID後返回值
• 若可取得lesson_id、無法取得id_token，則返回BadRequest

取得試卷

{Header}

{POST} {Domain}/hiteach/get-paper

成功返回

{
    "papers":                                                          //試卷列表 [Array]
    [ 
        {
                "name": "2020年上學期一年級數學科期中考",                //試卷名稱 [String]
                "blob": "/paper/2020年上學期一年級數學科期中考/",        //試卷blob相對路徑 [String]
                "periodId": "463db08d-cbe7-48a0-a81a-fc39b3c1fep1",    //學段ID [String]
                "gradeIds": [                                          //年級ID [Array]
                    "1379ac00-ccaf-4bb4-9dae-1fccb0031421",
                    "8d9aedbb-c81d-4c07-8f6d-3b8cc6be7ca2"
                ],
                "subjectId": "8b94c6b6-2572-41e5-89b9-a82fcf13891e",   //科目ID [String]
                "subjectName": "语文",                                 //科目名稱 [string]
                "itemCount": 10,                                       //題目數 [Int]
                "score": 100, (試卷總分)                                //試卷總分 [Int]
                "useCount": 0, (引用次數)                               //引用次數 [Int]
                "createTime": 1610525739208 (創建時間)                  //創建時間(Milliseconds) [Long]
        },
    ],
    "totalCount": 32                                                   //試卷總數 [Int]
}

取得試題

{Header}

{POST} {Domain}/hiteach/get-item

成功返回

{
    "items":                                                                //試題列表 [Array]
        [ 
            {
                "id": "hbcntest-t001-t002-t003-t0000000001",                //試題ID [string]
                "type": "single",                                           //試題類型 [string] single: 单选题, multiple: 多选题, judge: 判断题, complete: 填空题, subjective: 问答题, compose: 综合题)
                "blob": "/item/hbcntest-t001-t002-t003-t0000000001.json",   //試題blob相對路徑 [string]
                "periodId": "463db08d-cbe7-48a0-a81a-fc39b3c1fep1",         //學段ID [string]
                "gradeIds": [                                               //年級ID [Array]
                    "1379ac00-ccaf-4bb4-9dae-1fccb0031421",
                    "8d9aedbb-c81d-4c07-8f6d-3b8cc6be7ca2"
                ],
                "subjectId": "8b94c6b6-2572-41e5-89b9-a82fcf13891e",        //科目ID [string]
                "subjectName": "语文",                                      //科目名稱 [string]
                "field": 1,                                                 //認知層次 [Int] 1:知識, 2:理解, 3:應用, 4:分析, 5:綜合, 6:評鑑)
                "level": 1,                                                 //等級 [Int] 1:容易 2:較易 3:一般 4:較難 5:困難
                "useCount": 0,                                              //引用次數 [Int] 
                "createTime": 1610525739208 (創建時間)                       //創建時間(Milliseconds) [Long]
            },
        ],
    "totalCount": 32                                                        //試題總數 [Int]
}

上傳評測結果

{POST} {Domain}/hiteach/upd-exam-result

上傳評測JSON架構：

{
    "exam":{
        "pk": "Exam",  //分類，固定字串:Exam
        "code": "Exam-hbcn", //分區鍵 校園評測：Exam-{學校ID}  個人評測：Exam-{TMID}
        "id": "8825fbc3-97e7-4596-a7bd-5254a77dec88", //評測ID(GUID)
        "name": "評測名稱", //評測名稱
        "school": "hbcn", //學校ID(無者為null)
        "creatorId": "1595321354", //創建人TMID
        "stuCount": 55,  //施測學生數
        "createTime": 1611303659994,  //創建評測時間
        "startTime": 1611303659932, //施測開始時間
        "endTime": 1611417599999,  //施測結束時間
        "publish": "0",  //發布模式 0:立即發布 1:定時發布
        "year": 2021, //學年
        "range": "school", //評測範圍 校級:school 個人:null
        "source": "0", //0:线上评量 1:课中评量 2:阅卷评量 ※由HiTeach發起的評測活動為1
        "classes": [ "hbcn0701", "hbcn0702" ],//行政班級ID  ※原名targetClassIds，2021-3-25名稱變更為classes
        "stuLists": [ "15dbc495-5153-8987", "15dbc495-5153-4524" ],//教學班ID或個人班級ID ※2021-08-17追加
        "papers": [
            {
                "id": "392fda81-67a9-ce32-d936-d8967ea02d6c", //試卷ID ※不從IES5來者為null
                "code": "Paper-hbcn",  //試卷分區鍵 ※不從IES5來者為null
                "name": "学情分析用卷", //試卷名稱
                "blob": "/exam/8825fbc3-97e7-4596-a7bd-5254a77dec88/paper/392fda81-67a9-ce32-d936-d8967ea02d6c", //上傳的blob  路徑：/exam/{評測ID}/paper/{試卷ID}
                "scope": "school",  //試卷個人學校屬性 
                "multipleRule": 3, //多選題配分規則 1:全對得滿分(default) 2:少選得一半分數，不選不得分 3:少選按個數得分，錯選或不選不得分 4:依照(選項數-2*錯選數)/選項數，負分不得分
                "point": [ 20, 20, 25, 25 ], //此試卷所有題目配分 
                "answers": [  //此試卷所有題目正確答案 ※每題以array方式
                    ["A"],  //第一題(單選例)
                    ["C","D"], //第二題(複選例)
                    ["tomorrow"], //第三題(填充問答例)
                    [] //第四題(無正解例)
                ],
                "knowledge": [  //此試卷所有題目知識點列
                    ["图形","计算"],
                    ["实数"],
                    [],
                    []
                ],
                "field": [ //此試卷所有題目認知層次 1:知識 2:理解 3:應用 4:分析 5:綜合 6:評鑑   預設:1
                    5,
                    4,
                    2,
                    1
                ], 
            }
        ],
        "type": "regular",  //測試類別 regular: 正规考 simulation:模拟考 normal:普通考
        "period": {  //學段
            "id": "ca484aa8-e7b5-4a7c-8ef3-bd9e7b7d4fp2",
            "name": "初中"
        },
        "grades": [  //年級
            {
                "id": "b1744900-6546-4b39-9d88-a20991494aa7",
                "name": "七年级"
            }
        ],
        "subjects": [  //校園評測：科目資訊  個人評測：課程資訊
            {
                "id": "ac73f07d-2cc8-4174-85ae-b39cc5b6beef",  //校園評測：科目ID  個人評測：課程ID
                "name": "数学",  //校園評測：科目名稱  個人評測：課程名稱
                "classCount": 4  //施測班級數
            }
        ],
        "blobUrl": "/exam/6e05ebdf-a667-4c4b-9c66-cc9ab2ab69b4",  //blob位置
        "progress": "finish",  //評測進行狀態 未發布:pending  進行中:going  完成:finish
        "scope": "school",  //評測對象為校本班級：school  評測對象為私人課程：private [2021-4-14變更]
        "owner": "teacher",  //評測類型  校園評測：school  個人評測：teacher  [2021-4-22追加]
        "examType": {  //考試類型 [Object]  ※學校可自訂 會於get-school-info時拿到，無者為null
            "id": "23a7da4e-ac87-302b-3fd5-d4657cbecb9f",
            "name": "月月测"
        }
    },
    "examClassResult": [
        {
            "code": "ExamClassResult-hbcn",  //分區鍵 評測對象為校本班級：ExamClassResult-{學校ID}  評測對象為私人課程：ExamClassResult-{個人ID}
            "pk": "ExamClassResult",
            "id": "e61bfa99-b39d-470e-b0ba-4074c1d54e68", //識別ID(自由生成)
            "school": "hbcn",  //學校ID
            "examId": "57ce1952-1b40-4cc1-9058-d01cd05cca56", //評測ID
            "subjectId": "ac73f07d-2cc8-4174-85ae-b39cc5b6beef", //校園評測：時：科目ID  個人評測時：課程ID
            "gradeId": "b1744900-6546-4b39-9d88-a20991494aa7", //年級ID
            "year": 2021,  //學年
            "info": {  //班級資訊
                "id": "27e0a941-259e-be9e-6bdd-6f67c3aca8d2",  //班級ID
                "name": "七年级三班"  //班級名稱
            },
            "progress": true,  //是否已完成 false:進行中 true:已完成
            "studentIds": [  //學生ID
                "hbcn070301",
                "hbcn070302",
                "hbcn070303"
            ],
            "studentAnswersArray": [  //學生作答結果blob路徑  ※路徑規則：{examId}/{subjectId}/{studentId}/ans.json
                [ "cd6b3c00-ca3f-4a55-a8e4-98bff1552b69/8b94c6b6-2572-41e5-89b9-a82fcf13891e/25038/ans.json" ], //第一位學生的答案blob路徑 
                [ "cd6b3c00-ca3f-4a55-a8e4-98bff1552b69/8b94c6b6-2572-41e5-89b9-a82fcf13891e/25039/ans.json" ] 
            ],
            "studentScores": [  //學生各題成績
                [ 10, 20, 5 ]  //第一位學生各題的成績
                [ 10, 0, 0 ]
            ],
            "scope": "school", //評測屬性 評測對象為校本班級：school  評測對象為私人課程：private [2021-4-14變更]
            "sum": [  //學生總分
                81,
                58,
                48
            ]
        }
    ],
    "blobUploaded": false, //HiTeach是否已上傳檔案至Blob (若為true則此API不會搬運檔案)
    "blobCopyPath":[ //要拷貝的檔案路徑 會將此路徑下的所有檔案拷貝至 exam/{Exam.id}/{SubjectId}/ 的下面
        "temp/records/f12252a91f30fb171193891616131270229/Exam/4295180980899020800"
    ],
    "recordSwitch": true, //拷貝源Blob是否因對象不同而切換學校或個人 true時，對象為學校班級則拷貝源Blob會設定為學校ID；false則對象為學校班級也只會從老師個人ID取得資料
    "cloudas": true //是否啟動cloudas運算
}

此API若上傳相同評測ID資料則會更新原資料，無原資料則新建。

各種評測類型整理

[校園評測]
Exam.code: Exam-{學校ID}
Exam.scope: school
Exam.owner: school
blob: {學校ID}/exam/...

[個人評測 校本課程(教室)]
Exam.code: Exam-{個人ID}
Exam.scope: school
Exam.owner: teacher
blob: {學校ID}/exam/...

[個人評測 個人課程(教室)]
Exam.code: Exam-{個人ID}
Exam.scope: private
Exam.owner: teacher
blob: {個人ID}/exam/...

成功返回

{
    "error": 0,
    "message": ""
}

※註：(2021-7-13式樣)由於給予HiTeach學校Blob讀寫權限，上傳評測結果API不再執行以下處理：

1. (1) 將課程記錄下的試卷資料拷貝至學校/個人評測下的試卷資料 (2)改寫評測資料試卷Blob位置的值(exam.papers.blob)
   [From]/records/{課程記錄ID}/ExamPaper/{試卷ID}/ [To]/exam/{評測ID}/paper/{試卷ID}/
   
2. (1)將學生答案上傳學校/個人blob後 (2)填入學生作答檔案位置(examClassResult.studentAnswersArray)
   

取得課綱 [未完成]

{Header}

{POST} {Domain}/hiteach/get-syllabus

成功返回

[  (老師的校本課綱)
      {
            "id": "56fecf23-7b45-4407-86ef-81feaf8ba244", (卷ID)
            "name": "數學第一卷", (卷名稱)
            "resourceCount": 1, (關聯資源數)
            "itemCount": 1, (關聯試題數)
            "structure": [ (此課綱架構 第一層為卷資料，"children"中為所屬階層架構)
                {
                    "id": "56fecf23-7b45-4407-86ef-81feaf8ba244", 
                    "name": "數學第一卷",
                    "children": [
                        {
                            "id": "99c0adcd-74e7-4b41-a3f2-cc6f9534203c",
                            "name": "數學第一卷第一章",
                            "children": [...(以下略)]
                        }
                    ]
                }
            ]
       }
   ],

取得知識點 [未完成]

{Header}

{POST} {Domain}/hiteach/get-knowledge

成功返回

[  (知識點列表)
       {
           "id": "aa617cc3-7347-4cf6-b327-0371ffceca78",
           "name": "錯讀音"
       }
   ]

學生簡易Login [未完成]

不須提供 {Header}

{POST} {Domain}/student/login-simple

成功返回

{
    "error": 0, 
    "auth_token": "aa617cc373474cf6-b3270371ffceca78....."
}

HiTeach Blob相關操作

HiTeach 活動結束上傳紀錄

路徑: {學校}{個人}/records
動作: 寫入

HiTeach 儲存本地名單

路徑: {個人}/local
動作: 寫入