API 資源

bookmark_border 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

如需 API 資源和方法的詳細資訊，請參閱 Classroom API 參考資料。

資源關係總覽

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

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 UI 的「訊息串」頁面頂端建立 Announcements。老師只要在「課堂作業」分頁中按一下「建立」按鈕，即可建立 CourseWork 和 CourseWorkMaterials。開發人員可以透過 Classroom API 以程式設計方式建立所有串流項目類型。

以下是串流項目的正確做法：

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

已複製的串流項目

老師可以複製課程、重複使用作業，或是將串流項目發布至多門課程，以複製串流項目。任何新副本都會有專屬 ID，如果您要開發 Classroom 外掛程式，這項資訊可能會是重要的考量。請參閱複製內容指南，瞭解外掛程式如何處理這些情境。

課堂作業和學生提交內容

CourseWork 項目代表課程中一群學生的作業。這是唯一可接受學生提交內容的串流項目類型。CourseWork 資源包含說明、截止日期、最高成績等詳細資料，以及建立時間等中繼資料。

每個 CourseWork 資源都會說明下列任一類型的任務：

• 學生透過提交工作表或其他附件來完成的作業。
• 簡答題或選擇題。

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

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

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

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

課程作業材料和公告

與 CourseWork 類似，CourseWorkMaterials 代表指派給課程中一組學生的內容。每個資源都包含標題、說明和附加資料等詳細資料。不過，與 CourseWork 不同，CourseWorkMaterials 不需要學生提交任何構件。因此，CourseWorkMaterials 沒有截止日期，也沒有 StudentSubmissions。老師可能會使用 CourseWorkMaterials 張貼建議閱讀內容、課程大綱或課堂規則。

Announcements 也代表與一群學生分享的內容，但沒有標題等詳細資料，也無法依 Topics 排序，例如 CourseWork 或 CourseWorkMaterials。老師可能會使用這些功能向班級宣布提醒事項或通知。

主題

Topics 可用於在類別中視覺化排列 CourseWork 和 CourseWorkMaterials。例如，您可以使用這些標籤將作業分組為「選修」和「必修」，或是「單元 1」和「單元 2」。

Classroom 外掛程式

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

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

• 活動附件需要學生完成並提交個別提交內容。例如測驗、圖表或遊戲。您可以選擇為活動提交內容評分。
• 您不需要要求學生提交內容附件。學生不需要繳交附件，也不會評分。例如相片、文章和影片。

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

註冊項目

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

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