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，在 Webhook 上接收通知，或輪詢訂閱端點。

如要設定 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) 權限，允許該帳戶發布至您的主題。

註冊應用程式以接收通知

建立 Classroom API 推播通知服務帳戶可發布的主題後，即可使用 registrations.create() 方法註冊通知。registrations.create() 方法會驗證推送通知服務帳戶是否可連線至提供的 Cloud Pub/Sub 主題。如果推播通知服務帳戶無法連上主題 (例如主題不存在，或您未授予該帳戶主題的發布權限)，這個方法就會失敗。

授權

與所有 Classroom API 呼叫一樣，對 registrations.create() 的呼叫也必須使用授權權杖這個驗證權杖必須包含「推播通知」範圍 (https://www.googleapis.com/auth/classroom.push-notifications)，以及查看通知傳送相關資料所需的任何範圍。

  • 如果是班表變更動態消息，則表示班表範圍或 (理想情況下) 其唯讀變數 (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() 取消註冊通知。