Classroom API 的推播通知

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

本文將提供概念總覽，並說明如何開始接收推播通知。

Classroom 推播通知總覽

Classroom API 推播通知功能可讓使用 Classroom API 的應用程式在 Classroom 中資料異動時訂閱通知。通知會傳送至 Cloud Pub/Sub 主題，通常會在變更後的幾分鐘內傳送。

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

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

  • 目的地是指通知傳送的位置。
  • 動態饋給是第三方應用程式可訂閱的通知類型。例如：「課程 1234 的學生名單變更」。
  • 註冊是 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 主題 (最簡單的方法)，也可以透過指令列工具 (用於簡單的程式設計用途) 或使用 Cloud Pub/Sub API 建立。請注意，Cloud Pub/Sub 只允許有限數量的主題，因此如果應用程式變得熱門，使用一個主題接收所有通知，就能確保不會發生縮放問題。

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

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

注意：如果您授予推播通知服務帳戶權限，允許該帳戶發布至 Cloud Pub/Sub 主題，那麼能向 Developer Console 專案提出要求的使用者就能判斷該專案是否存在，並註冊相關通知。許多應用程式會在用戶端儲存 OAuth 用戶端 ID，因此使用者或許能夠透過您的開發人員控制台專案提出要求。如果您符合上述情況，且擔心使用者會傳送不必要的通知至您的 Cloud Pub/Sub 主題，或是知道您用於推播通知的 Cloud Pub/Sub 主題名稱，建議您考慮從其他開發者控制台專案註冊推播通知。

註冊應用程式以接收通知

有了 Classroom API 推播通知服務帳戶可發布的主題後，您就可以使用 registrations.create() 方法註冊通知。registrations.create() 方法會驗證推播通知服務帳戶是否可以存取所提供的 Cloud Pub/Sub 主題。如果推播通知服務帳戶無法觸及主題，此方法就會失敗，例如主題不存在，或是您未授予該主題的發布權限。

授權

如同所有 Classroom API 呼叫，對 registrations.create() 的呼叫必須經過授權，才能使用授權權杖。這個驗證權杖必須包含推播通知權限範圍 (https://www.googleapis.com/auth/classroom.push-notifications)，以及查看哪些通知傳送資料所需的任何權限範圍。

  • 對藝人名單變更動態饋給而言，這是指 Rosters 範圍，或 (理想情況下) 其唯讀變化版本 (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()。同樣地，對 courses.courseWork 集合的變更會產生 courseId 和 id 欄位，可將未經修改的資料傳送至 courses.courseWork.get()，而對 courses.courseWork.studentSubmissions 集合的變更會產生 courseId、courseWorkId 和 id 欄位，可將未經修改的資料傳送至 courses.courseWork.studentSubmissions.get()。

以下程式碼片段示範通知範例：

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

通知也具有 registrationId 訊息屬性，內含造成通知的註冊 ID，可與 registrations.delete() 搭配使用，取消註冊通知。