Classroom API 的推播通知

您可以使用 Registrations 集合中的方法，在 Classroom 中的資料變更時收到通知。

本文提供概念總覽，以及有關如何開始接收推播通知的簡單操作說明。

Classroom 推播通知總覽

Classroom API 推播通知功能可讓應用程式透過 Classroom API 訂閱，在 Classroom 中的資料發生變更時接收通知。通知會傳送到 Cloud Pub/Sub 主題，通常在變更後的幾分鐘內。

如要接收推播通知，您必須設定 Cloud Pub/Sub 主題，並在為適當的通知動態饋給建立註冊時，提供該主題的名稱。

以下是本文件使用的重要概念定義：

  • 目的地是指傳送通知的位置。
  • 動態饋給是第三方應用程式可訂閱的通知類型。例如「課程 1234 的學生名單異動」。
  • 註冊是 Classroom API 的指令，可指示 Classroom API 將特定動態饋給的通知傳送至目的地。

建立動態饋給的註冊作業後，註冊的 Cloud Pub/Sub 主題會收到該動態饋給的通知，直到到期為止。註冊約期會持續一週，但只要在註冊約期到期前隨時向 registrations.create() 提出相同的要求，就能延長註冊約期。

您的 Cloud Pub/Sub 主題只會收到資源通知，這些資源可透過您在建立註冊時提供的憑證查看。舉例來說，如果使用者撤銷應用程式的權限，或是以老師身分移除權限，系統就不會再發送通知。

動態饋給類型

Classroom API 目前提供三種動態饋給類型：

  • 每個網域都有「網域成員名單變更」動態饋給，系統會在學生和老師加入及離開該網域的課程時發出通知。
  • 每個課程都有「課程學生名單異動」動態饋給，系統會在學生和老師加入及離開該課程時傳送通知。
  • 每個課程都有課程作業變更動態饋給，當在該課程中建立或修改任何課程作業或學生提交物件時，系統會顯示通知。

設定 Cloud Pub/Sub 主題

通知會傳送至 Cloud Pub/Sub 主題。從 Cloud Pub/Sub 中，您可以透過網路掛鉤或輪詢訂閱端點來接收通知。

如要設定 Cloud Pub/Sub 主題，您必須執行下列操作：

  1. 請確認您已符合 Cloud Pub/Sub 必要條件。
  2. 設定 Cloud Pub/Sub 用戶端。
  3. 查看 Cloud Pub/Sub 定價，並為 Developer Console 專案啟用計費功能。

  4. 在開發人員主控台中 (簡單地透過工具)、使用指令列工具 (簡易程式輔助) 或使用 Cloud Pub/Sub API 建立 Cloud Pub/Sub 主題。請注意，Cloud Pub/Sub 僅允許特定的主題，因此使用一個主題接收所有通知，可確保即便應用程式變得很熱門，也不會遇到資源調度問題。

  5. 在 Cloud Pub/Sub 中建立訂閱項目，以指示 Cloud Pub/Sub 如何傳送通知。

  6. 最後，在註冊推播通知之前，您需要授予推播通知服務帳戶 (classroom-notifications@system.gserviceaccount.com) 的權限，才能將內容發布至主題。

注意：如果您授予推播通知服務帳戶權限，讓該帳戶發布至您的 Cloud Pub/Sub 主題，使用者就能透過 Developer Console 專案提出要求，即可判斷該專案是否存在，並註冊接收相關通知。許多應用程式都會在用戶端儲存 OAuth 用戶端 ID，因此使用者或許可以從您的 Developer Console 專案發出要求。如果遇到這種情況，且您擔心使用者會不必要的通知到您的 Cloud Pub/Sub 主題，或是知道您用於推播通知的 Cloud Pub/Sub 主題名稱，則應考慮從其他 Developer Console 專案註冊推播通知。

註冊應用程式以接收通知

決定了 Classroom API 推播通知服務帳戶可發布的主題後，您可以使用 registrations.create() 方法註冊以註冊通知。registrations.create() 方法會驗證推播通知服務帳戶是否能存取您提供的 Cloud Pub/Sub 主題。如果推播通知服務帳戶無法到達主題，這個方法就會失敗；舉例來說，假如主題不存在，或是您尚未授予該主題的發布權限，就無法這麼做。

授權

和所有對 Classroom API 的呼叫一樣，對 registrations.create() 的呼叫必須取得授權，並提供授權權杖。這個驗證權杖必須包含推播通知範圍 (https://www.googleapis.com/auth/classroom.push-notifications)，以及所需的任何範圍，才能查看要傳送哪些通知的相關資料。

  • 對學生名單變更動態饋給來說，這表示 Roster 範圍或 (理想情況) 其唯讀變化版本 (https://www.googleapis.com/auth/classroom.rosters.readonly 或 https://www.googleapis.com/auth/classroom.rosters)。
  • 如為課程作業變更動態饋給，這是指「學生」的課程作業範圍，或 (理想情況) 的唯讀變化版本 (https://www.googleapis.com/auth/classroom.coursework.students.readonly 或 https://www.googleapis.com/auth/classroom.coursework.students)。

如要傳送通知，應用程式必須保留具有所需範圍的授權使用者授予的 OAuth 授權。如果使用者取消連結應用程式，通知便會停止。請注意，目前不支援全網域授權委派。如果您嘗試只使用全網域委派授權進行註冊，就會收到 @MissingGrant 錯誤。

接收通知

通知使用 JSON 編碼，並包含下列內容：

  • 含有已變更資源的集合名稱。如果是學生名單變更的通知，則為 courses.students 或 courses.teachers。如果是課程工作變更，則為 courses.courseWork 或 courses.courseWork.studentSubmissions。
  • 在地圖上變更資源的 ID。這張對應旨在將引數與適當資源的 get 方法進行比對。如果是學生名單變更的通知，系統會填入 courseId 和 userId 欄位，而且可以不修改這些欄位，然後傳送至 courses.students.get() 或 courses.teachers.get()。同樣地，變更課程的 courseId 和 id 欄位將可{<學生提交作業>，並可以套用未修改的courseWorkId檔案。courseIdidcourses.courseWork.get()courses.courseWork.studentSubmissions.get()

下列程式碼片段為通知範例：

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

通知也有 registrationId 訊息屬性，包含導致通知的註冊 ID，可以搭配 registrations.delete() 使用，從通知中取消註冊。