Classroom API 的推播通知
透過集合功能整理內容你可以依據偏好儲存及分類內容。

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

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

Classroom 推播通知總覽

Classroom API 推播通知功能可讓使用 Classroom API 的應用程式在 Classroom 中資料異動時訂閱通知。通知會傳送到雲端 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 主題，您必須執行下列操作：

確認您已執行 Cloud Pub/Sub 必要條件。
設定 Cloud Pub/Sub 用戶端。
查看 Cloud Pub/Sub 定價。並為 Developer Console 專案啟用計費功能。
您可以在「開發人員控制台」中建立 Cloud Pub/Sub 主題 (最簡單的方法)，也可以透過指令列工具 (用於簡單的程式設計用途) 或使用 Cloud Pub/Sub API 建立。請注意，Cloud Pub/Sub僅允許一定數量的主題，因此使用單一主題確保在適當情況下，不會發生資源調度問題變得十分熱門
在 Cloud 中建立訂閱項目透過 Pub/Sub 告訴 Cloud Pub/Sub 如何傳送通知。
最後，在註冊推播通知前，您需要授予推播通知服務帳戶 ([email protected]) 權限，以便發布至主題。

注意：如果您授予推播通知服務帳戶發布權限附加至 Cloud Pub/Sub 主題，也就是能向開發人員提出要求的使用者控制台專案將可判斷該專案是否存在，並向通知它。許多應用程式會將 OAuth 用戶端 ID 儲存在用戶端因此使用者也許能透過 Developer Console 提出要求專案。如果遇到這種情況，且您對於將一般使用者接收不必要的通知，或是知道 Cloud Pub/Sub 主題應考慮用於推播通知的 Pub/Sub 主題從其他 Developer Console 專案註冊推播通知。

註冊應用程式以接收通知

為 Classroom API 推播通知服務帳戶設定主題後發布通知，您可以使用 registrations.create() 方法。registrations.create() 方法會驗證提供的推播通知服務帳戶可以存取 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(). 同樣地，對 course.courseWork 集合的變更也會 courseId 和 id 欄位可未經修改 courses.courseWork.get() 以及 Course.courseWork.studentSubmissions 集合的變化 courseId、courseWorkId 和 id 欄位可供未經修改傳送到 courses.courseWork.studentSubmissions.get().

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

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

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

Classroom API 的推播通知 透過集合功能整理內容 你可以依據偏好儲存及分類內容。