簡介

如果教師同時使用 Classroom 和第三方工具，就必須在多個平台上設定課程和學生名單。您可透過上傳 CSV 或逐一輸入電子郵件，以手動方式完成。不過，只要使用 Classroom API，第三方工具就能整合以下 API 最常見的用途，藉此減少老師的工作負載：學生名單匯入功能。

學生名單匯入功能可讓第三方平台透過老師或管理員權限，逐一擷取課程的中繼資料、老師和學生。老師可以擷取自己教授的課程詳細資料，管理員則可存取「整個網域中所有課程」的詳細資料。這種靈活彈性可讓開發人員使用管理員憑證，無論是個別老師的等級，還是整個網域的整個網域，都能順暢地將 Classroom 學生名單加入自己的平台。

在深入探討學生名單匯入功能可能呈現的技術細節之前，我們先來看看範例工作流程：

  1. 在第三方應用程式中，老師可以選擇匯入 Classroom 課程。

  2. 第三方應用程式會透過 Classroom API 呼叫 courses.list 方法，藉此傳回包含老師所有課程的回應 JSON。

  3. 在 JSON 回應中，第三方應用程式會顯示老師課程名稱，以供學生選擇課程。應用程式需要追蹤課程 ID，才能繼續進行下一個步驟。

  4. 使用所選課程 ID 後，第三方應用程式會呼叫 students.list 和 teachers.list 方法，並在其網站上顯示所有名稱，方便老師確認要匯入。

  5. 第三方應用程式會使用 students.list 和 teachers.list 回應 JSON 中傳回的電子郵件，邀請使用者加入平台上新匯入的課程。

針對工作流程中提及的每個方法，您可以使用 API Explorer 查看每個方法的確切行為。建議您在完成本指南之前，先執行下列預先讀取作業：

  1. 使用 Classroom API 管理課程
  2. 管理學生和老師

摘要說明上述學生名單匯入工作流程的圖表。

入門課程

實作 Classroom 學生名單匯入的具體細節之前，請先決定需要透過 API 擷取哪些課程和使用者資訊。您可以在參考說明文件中查看可用的課程中繼資料，但以下摘要說明部分必要或常見欄位：

欄位 使用
id 提出 API 要求來擷取學生或老師時，此為必填
名稱 方便使用者使用，例如顯示在您的網站
ownerId 如要正確識別課程的主要授課老師，就必須為整個網域進行匯入

此課程資訊是在上述工作流程的 courses.list 步驟中擷取。在這項要求中，您可以指定特定的要求參數。儘管這個方法並非必要項目，但我們建議採用以下參數：

參數 使用
courseState 如未指定，API 會傳回全部六個 課程狀態的課程。建議您指定 ACTIVE，擷取老師目前正在使用的課程。
pageSize 對於匯入自己的課程的老師，建議您指定小型 (10 以下) 的 pageSize，縮短 API 呼叫的回應時間。
pageToken 如果您使用分頁要求，則為必填。
teacherId 建議原因：網域管理員經常授課。如未指定，這類要求會傳回整個網域中的老師課程。
欄位 建議縮短 API 呼叫的回應時間。

應用程式現在可以使用先前擷取的課程 ID，擷取該課程或課程的學生和共同授課老師名單。此課程 ID 是 teachers.list 和 students.list 唯一的必要查詢參數，但您也可以考慮指定 pageSize 和 fields 參數，以縮短 API 呼叫的回應時間。

學生和老師資源的所有可用欄位可在各自的說明文件中找到。profile 欄位中最常使用且通常為必填欄位：profile.name 和 profile.emailAddress。

欄位 使用
profile.name 方便使用者使用，例如顯示在您的網站
profile.emailAddress 如果應用程式需要專門識別學生身分，就必須填寫本欄

如要從 Classroom 擷取及使用上述任一課程或學生名單詳細資料，應用程式必須要求使用者提供授權。如要實作這項工作流程，需要以下三個範圍：

  • https://www.googleapis.com/auth/classroom.courses.readonly
    • 提供 Google Classroom 課程的唯讀存取權
  • https://www.googleapis.com/auth/classroom.rosters.readonly
    • 提供 Google Classroom 課程 (老師和學生) 學生名單的唯讀存取權
  • https://www.googleapis.com/auth/classroom.profile.emails
    • 提供老師和學生電子郵件屬性的讀取權限

同步處理學生名單與 Pub/Sub 通知

隨著學年的進展，學生名單會隨著學生退出或新增課程而改變。新增 Pub/Sub 通知，就能讓第三方應用程式與 Classroom 學生名單保持同步。如要接收通知，您需要設定 Google Cloud Pub/Sub 主題，然後使用 Classroom API 註冊主題。這項註冊要求 Classroom 將特定動態消息的資料傳送至指定主題。這個動態資訊將是觸發重新與老師 Classroom 學生名單同步處理的事件。

使用推播通知需要額外指定範圍，因此不需要提交來進行驗證：

  • https://www.googleapis.com/auth/classroom.push-notifications
    • 允許應用程式註冊任何推播通知活動

透過推播通知說明學生名單匯入工作流程的圖表

如要進一步瞭解如何整合 Classroom 推播通知，請參閱管理推播通知指南。