簡介

如果老師同時使用 Classroom 和第三方工具，就必須在多個平台設定課程和學生名單，您可以手動執行這項操作，方法是上傳 CSV 檔案或逐一輸入電子郵件地址。不過，第三方工具可以整合 Classroom API 最常見的用途：匯入名單，藉此減輕老師的工作負擔。

第三方平台可透過學生名單匯入功能，取得課程的後設資料、老師和學生名單 (須具備老師或管理員權限)。老師可以擷取自己任教課程的詳細資料，管理員則可存取整個網域的所有課程詳細資料。開發人員可使用管理員憑證，在個別老師層級或整個網域中，將 Classroom 學生名單順暢地加入平台。

網域管理員可能會使用第三方工具，擔任自己課程的老師。透過 API 擷取課程詳細資料時，請務必謹慎處理網域管理員和老師權限的差異。

在深入瞭解名單匯入整合的技術細節前，我們先來看看工作流程範例：

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. 管理學生和老師

除了下方的流程圖，也請查看 ActivelyLearn 的即時範例，進一步瞭解這類整合方式。

開始使用

在實作 Classroom 學生名單匯入功能之前，您需要先決定要透過 API 擷取哪些課程和使用者資訊。如要瞭解可用的課程中繼資料，請參閱參考說明文件，但以下列出一些必要或常見的欄位：

欄位	使用
id	擷取學生或老師的 API 要求必須提供這項資訊
名稱	建議使用，方便使用者操作，例如在網站上顯示
ownerId	以網域為單位匯入時，必須提供這項資訊，才能正確識別課程的主要老師

這項課程資訊是在上述工作流程的 courses.list 步驟中擷取。您可以在這項要求中指定特定要求參數。雖然這個方法不需要任何參數，但建議使用下列參數：

參數	使用
courseState	如果未指定，API 會傳回所有六種 課程狀態的課程。建議您指定 ACTIVE，以便擷取老師目前使用的課程。
pageSize	如果老師要匯入自己的課程，建議指定較小的 pageSize (小於 10)，以縮短 API 呼叫的回應時間。
pageToken	如果您使用分頁要求，則必須提供這項資訊。
teacherId	建議使用這個選項，因為網域管理員通常會教授課程。如果未指定，要求會傳回整個網域中老師的課程。
欄位	建議縮短 API 呼叫的回應時間。

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

如要查看學生和老師資源的所有可用欄位，請參閱各自的說明文件。最常用且通常為必填的兩個欄位位於 profile 欄位中：profile.name 和 profile.emailAddress。

欄位	使用
profile.name	建議使用，方便使用者操作，例如在網站上顯示
profile.emailAddress	應用程式需要用來識別學生身分

如要從 Classroom 擷取及使用任何課程或名單詳細資料，應用程式必須向使用者要求授權。如要實作這項工作流程，必須使用下列三個 (3) 範圍：

• 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 推播通知，請參閱我們的管理推播通知指南。