簡介

同時使用 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 推播通知，請參閱管理推播通知指南。