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 價格，並為您的雲端控制台專案啟用帳單功能。

  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 主題的權限，則可透過開發人員控制台專案提出要求的使用者就能判斷該帳戶是否存在，並註冊接收通知。許多應用程式會在用戶端端儲存 OAuth 用戶端 ID，因此使用者可能會透過 Developer Console 專案提出要求。如果您符合上述情況，且擔心使用者會傳送不必要的通知至您的 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)，以及查看哪些通知傳送資料所需的任何權限範圍。

  • 對於名單變更動態饋給，這表示名單範圍或 (理想情況下) 其唯讀變化版本 (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() 搭配使用，從通知中取消註冊。