簡介

同時使用 Classroom 和第三方工具的老師，必須在多個平台上設定課程和學生名單，這項工作相當繁瑣。您可以手動執行這項操作，方法是使用 CSV 上傳功能或逐一輸入電子郵件地址。不過，透過 Classroom API，第三方工具可整合 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
  • 提供老師和學生的 email 屬性讀取存取權

由於其中一個範圍屬於機密範圍，因此您的應用程式必須完成驗證程序。

使用 Pub/Sub 通知同步名單

隨著學年推進，學生可能會放棄或新增課程，名單可能也會隨之變更。新增 Pub/Sub 通知後，第三方應用程式就能與 Classroom 學生名單保持同步。如要接收通知，您必須設定 Google Cloud Pub/Sub 主題，然後透過 Classroom API 註冊該主題。這項註冊作業是要求 Classroom 將指定動態饋給中的資料傳送至指定主題。這個動態饋給會觸發事件，以便重新與老師的 Classroom 學生名單重新同步。

視應用程式的用途而定，您可以針對個別課程或網域訂閱通知。

如要使用推播通知，您必須額外提供一個範圍，但不必提交驗證：

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

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