REST Resource: courses

資源：課程

Classroom 課程。

JSON 表示法 
{
  "id": string,
  "name": string,
  "section": string,
  "descriptionHeading": string,
  "description": string,
  "room": string,
  "ownerId": string,
  "creationTime": string,
  "updateTime": string,
  "enrollmentCode": string,
  "courseState": enum (CourseState),
  "alternateLink": string,
  "teacherGroupEmail": string,
  "courseGroupEmail": string,
  "teacherFolder": {
    object (DriveFolder)
  },
  "courseMaterialSets": [
    {
      object (CourseMaterialSet)
    }
  ],
  "guardiansEnabled": boolean,
  "calendarId": string,
  "gradebookSettings": {
    object (GradebookSettings)
  },
  "subject": string,
  "learningStandardSettings": {
    object (CourseLearningStandardSettings)
  },
  "levels": string
}
欄位
id

string

Classroom 指派給這個課程的 ID。

當 creating a course 時，您可以選擇在要求中將這個 ID 設為 alias string，藉此建立對應的別名。id仍由 Classroom 指派，且課程建立後就無法更新。

在課程更新遮罩中指定這個欄位會導致錯誤。
name

string

課程名稱。例如「10 年級生物」。必須提供名稱。長度必須介於 1 到 750 個字元之間，且為有效的 UTF-8 字串。
section

string

課程的章節。例如「第 2 節」。如要設定這個欄位，必須使用有效的 UTF-8 字串，且長度不得超過 2, 800 個半形字元。
descriptionHeading

string

說明的選用標題。例如：「歡迎來到 10 年級生物課。」如要設定這個欄位，必須使用有效的 UTF-8 字串，且長度不得超過 3600 個字元。
description

string

選填說明。舉例來說：「我們會透過教科書、客座講座和實驗室工作，瞭解生物的結構。敬請期待！」。如要設定這個欄位，必須使用有效的 UTF-8 字串，且長度不得超過 30,000 個字元。
room

string

選填會議室位置。例如「301」。如要設定這個欄位，必須使用有效的 UTF-8 字串，且長度不得超過 650 個字元。
ownerId

string

課程擁有者的 ID。

如果指定為 create course request 的參數，則必須填寫這個欄位。這個 ID 可以是下列任一項：

  • 使用者的數字 ID
  • 使用者的電子郵件地址
  • 字串常值 "me"，表示要求的使用者

這項設定必須在建立要求中設定。管理員也可以在 patch course request 中指定這個欄位，以轉移擁有權。在其他情況下，這項設定為唯讀。
creationTime

string (Timestamp format)

課程的建立時間。在課程更新遮罩中指定這個欄位會導致錯誤。

唯讀。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

本課程最近一次更新的時間。在課程更新遮罩中指定這個欄位會導致錯誤。

唯讀。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
enrollmentCode

string

加入這門課程時使用的註冊代碼。在課程更新遮罩中指定這個欄位會導致錯誤。

唯讀。
courseState

enum (CourseState)

課程狀態。如未指定，預設狀態為 PROVISIONED。
teacherGroupEmail

string

包含課程所有老師的 Google 群組電子郵件地址。這個群組不接受電子郵件，只能用於權限。

唯讀。
courseGroupEmail

string

包含課程所有成員的 Google 群組電子郵件地址。這個群組不接受電子郵件，只能用於權限。

唯讀。
teacherFolder

object (DriveFolder)

與課程所有老師共用的雲端硬碟資料夾資訊。

這個欄位只會為課程老師和網域管理員設定。

唯讀。
courseMaterialSets[]
(deprecated)

object (CourseMaterialSet)

顯示於本課程「關於」頁面的教材組合。

唯讀。
guardiansEnabled

boolean

這門課程是否已啟用監護人通知。

唯讀。
calendarId

string

所有課程成員都能查看的日曆 ID，Classroom 會在其中新增課程作業和公告的活動。

首次將課程設為 CourseState.ACTIVE 時 (建立課程時，或透過 UI 或 API 將課程更新為 ACTIVE 時)，系統會非同步建立課程日曆。建立程序完成後，系統才會填入日曆 ID。

唯讀。
gradebookSettings

object (GradebookSettings)

成績單設定，可指定如何計算學生的課程總成績，以及向誰顯示總成績。

唯讀。
subject

string

(選用步驟) 課程科目。
learningStandardSettings

object (CourseLearningStandardSettings)

(選用步驟)

課程中可用的學習標準相關設定。課程最多只能指派 5 個學習標準組合根節點。
levels

string

(選用步驟) 課程等級。例如：「9th grade」、「Middle school」、「4th - 5th」、「K-2」、「3000」。如果設定這個欄位，必須是有效的 UTF-8 字串，且少於 1000 個半形字元。

這個欄位只能使用 courses.patch 方法清除。

CourseState

課程可能處於的狀態。

列舉
COURSE_STATE_UNSPECIFIED 沒有課程狀態。系統不會在傳回的課程訊息中使用這個值。
ACTIVE 課程有效。
ARCHIVED 課程已封存。你只能將其變更為其他州別，無法修改。
PROVISIONED 課程已建立，但尚未啟用。主要任課老師和網域管理員可以存取這項設定，並修改或變更為 ACTIVE 或 DECLINED 狀態。只有在課程處於 DECLINED 狀態時，才能變更為 PROVISIONED。
DECLINED 課程已建立，但遭拒。課程擁有者和網域管理員可以存取這項資訊，但不會顯示在網頁使用者介面中。除了變更為 PROVISIONED 狀態外，您無法修改課程。只有在課程處於 PROVISIONED 狀態時，才能變更為 DECLINED。
SUSPENDED 課程已暫停。您無法修改課程，且只有 ownerId 所識別的使用者可以查看課程。如果課程可能違反《服務條款》，就會處於這種狀態。

CourseMaterialSet

課程「關於」頁面顯示的一組教材。包括課程大綱、時間表或與課程相關的其他背景資訊。

JSON 表示法 
{
  "title": string,
  "materials": [
    {
      object (CourseMaterial)
    }
  ]
}
欄位
title

string

這個組合的標題。
materials[]

object (CourseMaterial)

附加至這組教材的資料。

CourseMaterial

附加至課程的教材，屬於教材組合。

JSON 表示法 
{

  "driveFile": {
    object (DriveFile)
  },
  "youTubeVideo": {
    object (YouTubeVideo)
  },
  "link": {
    object (Link)
  },
  "form": {
    object (Form)
  }
}
欄位
聯集欄位 material。材料資料。material 只能是下列其中一項：
driveFile

object (DriveFile)

附加 Google 雲端硬碟檔案。
youTubeVideo

object (YouTubeVideo)

YouTube 影片附件。
form

object (Form)

Google 表單附件。

GradebookSettings

課程的成績單設定。詳情請參閱這篇說明中心文章。

JSON 表示法 
{
  "calculationType": enum (CalculationType),
  "displaySetting": enum (DisplaySetting),
  "gradeCategories": [
    {
      object (GradeCategory)
    }
  ]
}
欄位
calculationType

enum (CalculationType)

指出總成績的計算方式。
displaySetting

enum (DisplaySetting)

指出哪些人可以查看總成績。
gradeCategories[]

object (GradeCategory)

課程中可用的課業成績類別。

CalculationType

計算總成績的可能方法。

列舉
CALCULATION_TYPE_UNSPECIFIED 未指定方法。這項資訊不會退回。
TOTAL_POINTS 總成績是成績總和除以總分總和，與類別無關。
WEIGHTED_CATEGORIES 總成績是依類別計算的加權平均值。

DisplaySetting

顯示總成績的可能設定。

列舉
DISPLAY_SETTING_UNSPECIFIED 未指定任何設定。這項資訊不會退回。
SHOW_OVERALL_GRADE 在成績單和學生個人資料中向老師和學生顯示總成績。
HIDE_OVERALL_GRADE 不會在成績單或學生個人資料中顯示總成績。
SHOW_TEACHERS_ONLY 向老師顯示成績單和學生個人資料中的總成績。學生個人資料中不會顯示。

CourseLearningStandardSettings

課程的學習標準設定。

JSON 表示法 
{
  "standardSets": [
    {
      object (LearningStandardSetRoot)
    }
  ]
}
欄位
standardSets[]

object (LearningStandardSetRoot)

必填。套用至這門課程的學習標準根目錄組合。

LearningStandardSetRoot

代表所選學習標準集的根目錄。在 Classroom 使用者介面中，為串流項目設定學習目標時，系統會顯示所選根項目的後代。

JSON 表示法 
{
  "caseGuid": {
    object (CaseGuid)
  },
  "documentTitle": string,
  "standardTitle": string,
  "sourceDataAvailabilityStatus": enum (LearningStandardAvailabilityState)
}
欄位
caseGuid

object (CaseGuid)

必填。學習標準組合根目錄的 Satchel Rosetta Exchange GUID。
documentTitle

string

僅供輸出。學習標準組合根目錄的文件標題。
standardTitle

string

僅供輸出。學習標準組合根目錄的標題。
sourceDataAvailabilityStatus

enum (LearningStandardAvailabilityState)

僅供輸出。學習標準組合根目錄的可用性狀態。藉此判斷學習標準集根是否已從來源刪除。

CaseGuid

內含 CASE Network 提供的學習標準中繼資料。

JSON 表示法 
{
  "caseDocumentId": string,
  "caseItemId": string
}
欄位
caseDocumentId

string

必填。標準文件的專屬 ID (CASE 網路 GUID)。舉例來說，如果網址為：https://casenetwork.1edtech.org/c649d172-d7cb-11e8-824f-0242ac160002，則 caseDocumentId 為「c649d172-d7cb-11e8-824f-0242ac160002」。
caseItemId

string

(選用步驟) 學習標準的專屬 ID (CASE 網路 GUID)。舉例來說，如果網址為：https://casenetwork.1edtech.org/c649d172-d7cb-11e8-824f-0242ac160002/70d64823-d7cc-11e8-824f-0242ac160002，則 caseItemId 為「70d64823-d7cc-11e8-824f-0242ac160002」。

LearningStandardAvailabilityState

學習標準文件或項目的供應情形狀態。

列舉
LEARNING_STANDARD_AVAILABILITY_STATE_UNSPECIFIED 沒有可用性狀態。這個值絕不會傳回。
LEARNING_STANDARD_AVAILABLE 可用狀態，表示文件或項目仍存在於資料來源中。這是預設狀態。
LEARNING_STANDARD_ITEM_DELETED 已刪除狀態。表示項目已從資料來源中刪除。這項商品的部分資料欄位可能未填入資料。
LEARNING_STANDARD_DOCUMENT_DELETED 這個項目的上層文件已從資料來源中刪除。這項商品的部分資料欄位可能未填入資料。

方法

checkAddOnCreationEligibility
(deprecated)

 傳回使用者是否符合資格，可在指定課程中建立外掛程式附件。

checkGradingPeriodsSetupEligibility
(deprecated)

 傳回使用者是否符合資格，可更新特定課程的 GradingPeriodSettings。

create

 建立課程。

delete

 刪除課程。

get

 傳回課程。

getGradingPeriodSettings

 傳回課程中的評分週期設定。

list

 傳回要求使用者可查看的課程清單，但僅限符合要求的課程。

patch

 更新課程中的一或多個欄位。

update

 更新課程。

updateGradingPeriodSettings

 更新課程的評分週期設定。