API 資源

本指南提供 Google Classroom API 主要元件的總覽。Google Classroom API 包含資源和服務。資源代表 Google Classroom 中的實體，例如課程或作業，而服務則會擷取及管理這些資源。除了 Classroom 中的屬性外，部分實體還具有 API 專屬的其他屬性。主要實體類型包括：

實體	在 Classroom 中的表示法
課程	例如「M. 史密斯老師的第 4 節數學課」。
別名	課程的替代 ID。
邀請	將使用者加入課程的方法。
學生	課程中的學生。
老師	課程中的老師。
使用者設定檔	使用者，不限於學生或老師。
CourseWork	課程中的作業。
StudentSubmissions	學生為特定作業提交的內容，例如答案或工作表。
CourseWorkMaterials	課程中的學生教材。
公告事項	向課程中的學生發布公告。
AddOnAttachment	作業或教材中的內容或活動，通常會以嵌入式 iframe 顯示。
主題	課程中作業和教材的視覺化分組。
註冊	指示應用程式在資料 (例如課程學生名單) 異動時傳送通知。

大多數資源都有服務方法，可執行讀取、更新及刪除資源執行個體等標準作業。部分資源也有其他作業的自訂方法，例如修改指派特定作業的學生名單。

如要進一步瞭解 API 資源和方法，請參閱 Classroom API 參考資料。

資源關係總覽

• 課程是 Google Classroom 的基礎資料物件。
• 別名會做為 Courses 的替代 ID。
• 邀請可用於邀請使用者設定檔成為老師或學生，但 Google Workspace for Education 網域管理員也可以直接新增使用者。Course
• 老師可以建立串流項目，並與課程中的學生分享。可能的串流項目類型包括「作業」Coursework、「教材」CourseWorkMaterials 和「公告」Announcements。CourseWork 和 CourseWorkMaterials 可以視覺化方式整理成主題，並可包含 AddOnAttachments。學生提交 StudentSubmissions，以完成 CourseWork。
• 開發人員可以建立「註冊」，在部分資料變更時收到通知。

Google Classroom 適用於訂閱 Google Workspace for Education 的網域。在 Classroom 環境中，「網域」通常代表學區。您可以建立 Google Workspace for Education 測試網域，用於開發用途，這樣就能控管 Classroom 的實際運作例項，而不會影響實際使用者。

課程和別名

Courses 代表類別，例如「M. 史密斯老師的第 4 節數學課」，以及指派的老師、學生名單和中繼資料。每門課程都有伺服器指派的專屬 ID。Course 資源會封裝課程的所有中繼資料，例如名稱、說明、地點和時間。課程名單是透過「學生」、「老師」和「邀請」資源及其方法管理。

Aliases 是課程的替代 ID，可與課程建立關聯，並取代專屬 ID。每個別名都位於命名空間中，可限制別名的建立和查看權限。系統支援兩個命名空間：

• 網域：網域命名空間適用於建立所有使用者都需要存取，但與任何單一程式無關的別名。舉例來說，課程的替代清單 (例如 MATH 127 和 COMSCI 127) 應在網域命名空間中建立。網域命名空間中的別名只能由網域管理員建立，但網域中的所有使用者都能看到。
• 開發人員專案：開發人員專案命名空間可用於管理特定應用程式的別名。舉例來說，如果應用程式使用課程的替代 ID，可以建立別名，將其 ID 對應至 Classroom 課程。在這個命名空間中建立的別名會與特定 Google API 控制台繫結。應用程式的任何使用者都可以在該應用程式開發人員專案的命名空間中建立及查看別名。

如要進一步瞭解如何管理課程中繼資料和別名，請參閱「管理課程」。

課程名單和使用者

Students 和 Teachers 是使用者設定檔和課程之間的特定對應，代表使用者在課程中的角色。學生和老師的指定身分並非全域設定：使用者在一個課程中可獲派老師身分，在另一個課程中則可獲派學生身分。「學生」或「老師」代表特定使用者在特定課程中的一組權限。課程可能有多位老師，也可能沒有學生。老師和學生隨時可以加入或退出課程。

學生

Student 資源代表已註冊特定課程的學生。

學生可以查看課程詳細資料，以及課程的授課老師。

教師

Teacher 資源代表教授特定課程的使用者。

老師可以查看及變更課程詳細資料、查看老師和學生，以及管理其他老師和學生。

Invitations 和相關方法可讓您輕鬆將學生和老師加入課程。建立邀請後，使用者可以選擇是否加入課程，而不必透過老師和學生資源直接新增。

UserProfiles：代表使用者網域設定檔的對應項目，由 Directory API 傳回的使用者專屬 ID 或電子郵件地址識別。目前使用者也可以使用 "me" 簡寫，參照自己的 ID。

您也可以使用 UserProfiles 服務管理及邀請 Guardians，這是學生與監護人之間的對應關係。Classroom 中的監護人可以存取部分學生資訊，例如作業。

如要進一步瞭解如何管理名冊，請參閱「管理老師和學生」。

串流項目

串流項目是指發布給課程成員的內容。 開發人員和老師可以建立三種串流項目類型：Announcement、CourseWork 和 CourseWorkMaterial。

老師會在 Classroom 使用者介面的「訊息串」頁面頂端建立 Announcements。老師只要按一下「課堂作業」分頁中的「建立」按鈕，即可建立 CourseWork 和 CourseWorkMaterials。開發人員可透過 Classroom API，以程式輔助方式建立所有類型的串流項目。

串流項目具有下列特性：

• 所有串流項目都可以包含補充教材，例如 Google 雲端硬碟檔案、YouTube 影片、Google 表單、網址超連結和 Classroom 外掛程式附件。
• 所有訊息串項目都可以指派給課程中的部分學生。
• CourseWork 可能會評分或不評分。老師隨時可以變更CourseWork作業的評分狀態。
• 一個串流項目可能有多個附件。
• 串流項目可能包含不同類型的附件。舉例來說，一份作業可能同時包含 Google 雲端硬碟檔案、YouTube 影片和 Classroom 外掛程式附件。CourseWork
• 串流項目可能有多位開發人員提供的附加附件。
• 開發人員可以取得及修改任何含有外掛程式附件的訊息串項目資源詳細資料。
• 如果作業包含開發人員外掛程式的附件，開發人員可以繳交、收回或發還學生繳交的作業。CourseWork
• 開發人員只能在自己建立的作業中，為個別學生的提交內容給予最終成績。

已複製串流項目

老師可以複製課程、重複使用作業，或將動態消息項目發布到多門課程，藉此複製動態消息項目。所有新副本都會有專屬 ID，如果您要開發 Classroom 外掛程式，這可能是一項重要考量。請參閱複製內容指南，瞭解外掛程式如何處理這些情況。

CourseWork 和 StudentSubmissions

CourseWork 項目代表課程中一組學生的作業。只有這類訊息串項目可以接受學生繳交的作業。CourseWork 資源包含說明、截止日期、最高分數等詳細資料，以及建立時間等中繼資料。

每個 CourseWork 資源都會說明下列其中一種工作類型：

• 學生完成作業後，會繳交工作表或其他附件。
• 簡答題或選擇題。

CourseWork 項目中的學生作業會以 StudentSubmission 表示。其中包含回應和額外中繼資料，例如狀態和指派的等級。

StudentSubmission 的內容取決於對應的 CourseWork 項目類型，可能包括：

• 作業提交的試算表和附件，包括標題、縮圖和網址，以及可搭配適當 API (例如 Google 雲端硬碟或 YouTube) 使用的 ID。
• 簡答題或選擇題的答案。

如要進一步瞭解如何管理作業和學生提交內容，請參閱「管理作業」。

CourseWorkMaterials 和 Announcements

與 CourseWork 類似，CourseWorkMaterials 代表指派給課程中一組學生的內容。每個資源都有詳細資料，例如標題和說明，以及補充資料。不過，與 CourseWork 不同，CourseWorkMaterials 不會要求學生提交任何成果。因此，CourseWorkMaterials 沒有截止日期，也不存在 StudentSubmissions。老師可能會使用 CourseWorkMaterials 張貼建議讀物、課程大綱或課堂規則。

Announcements 也代表與一群學生共用的內容，但沒有標題等詳細資料，也無法像 CourseWork 或 CourseWorkMaterials 一樣依 Topics 整理。老師可能會使用這些功能，向全班發布提醒事項或通知。

主題

Topics 可用來在課程中以視覺化方式整理 CourseWork 和 CourseWorkMaterials。例如，您可能會將作業分組為「選做」和「必做」，或是「單元 1」和「單元 2」。

Classroom 外掛程式

外掛程式是由開發人員提供的 UI 和後端，通常會顯示在 iframe 中。外掛程式會顯示為串流項目的附件。串流項目可以是任何 Announcements、CourseWork 或 CourseWorkMaterials。外掛程式附件會以 AddOnAttachment 表示。

外掛程式附件可以是活動或內容。

• 學生必須完成並繳交個別作業，才能使用活動附件。例如測驗、繪圖或遊戲。活動提交內容可選擇是否要評分。
• 內容附件不需要學生繳交作業。學生不必繳交附件，也不會獲得評分。例如相片、文章和影片。

詳情請參閱外掛程式開發指南。

註冊項目

應用程式可以訂閱通知，在 Google Classroom 中特定資料異動時接收通知。例如更新課程名單時。Registrations 代表將這些通知傳送至應用程式的指令。

詳情請參閱推播通知指南。