Thông báo đẩy trong API Lớp học

Bạn có thể sử dụng các phương thức trong tập hợp Registrations để nhận thông báo khi dữ liệu thay đổi trong Lớp học.

Bài viết này cung cấp thông tin tổng quan về khái niệm cùng với hướng dẫn đơn giản về cách bắt đầu nhận thông báo đẩy.

Tổng quan về thông báo đẩy của Lớp học

Tính năng thông báo đẩy của Classroom API cho phép các ứng dụng sử dụng Classroom API đăng ký nhận thông báo khi dữ liệu thay đổi trong Lớp học. Thông báo được gửi đến một Cloud Pub/Sub chủ đề, thường là trong vòng vài phút sau khi có thay đổi.

Để nhận thông báo đẩy, bạn cần thiết lập một chủ đề Cloud Pub/Sub và cung cấp tên của chủ đề đó khi tạo đăng ký cho nguồn cấp dữ liệu thông báo thích hợp.

Dưới đây là định nghĩa về các khái niệm chính được sử dụng trong tài liệu này:

  • Đích đến là nơi gửi thông báo.
  • Nguồn cấp dữ liệu là một loại thông báo mà ứng dụng bên thứ ba có thể đăng ký. Ví dụ: "thay đổi danh sách cho khoá học 1234".
  • Đăng ký là một hướng dẫn cho Classroom API để gửi thông báo từ một nguồn cấp dữ liệu cụ thể đến một đích đến.

Sau khi bạn tạo một đăng ký cho nguồn cấp dữ liệu, chủ đề Cloud Pub/Sub của đăng ký đó sẽ nhận thông báo từ nguồn cấp dữ liệu đó cho đến khi hết hạn. Đăng ký của bạn kéo dài một tuần, nhưng bạn có thể gia hạn bất cứ lúc nào trước khi hết hạn bằng cách đưa ra yêu cầu giống hệt với registrations.create().

Chủ đề Cloud Pub/Sub của bạn chỉ nhận thông báo về những tài nguyên mà bạn có thể xem bằng thông tin xác thực mà bạn cung cấp khi tạo đăng ký. Ví dụ: nếu người dùng thu hồi quyền của ứng dụng hoặc bị xoá khỏi vai trò giáo viên, thì thông báo sẽ không còn được gửi.

Các loại nguồn cấp dữ liệu

Classroom API cung cấp 3 loại nguồn cấp dữ liệu:

  • Mỗi miền có một nguồn cấp dữ liệu thay đổi danh sách cho miền, nguồn cấp dữ liệu này hiển thị thông báo khi học viên và giáo viên tham gia và rời khỏi các khoá học trong miền đó.
  • Mỗi khoá học có một nguồn cấp dữ liệu thay đổi danh sách cho khoá học, nguồn cấp dữ liệu này hiển thị thông báo khi học viên và giáo viên tham gia và rời khỏi các khoá học trong khoá học đó.
  • Mỗi khoá học có một nguồn cấp dữ liệu thay đổi bài tập trên lớp cho khoá học, nguồn cấp dữ liệu này hiển thị thông báo khi bất kỳ bài tập trên lớp hoặc đối tượng bài nộp của học viên nào được tạo hoặc sửa đổi trong khoá học đó.

Thiết lập chủ đề Cloud Pub/Sub

Thông báo được gửi đến các chủ đề Cloud Pub/Sub. Từ Cloud Pub/Sub, bạn có thể nhận thông báo trên webhook hoặc bằng cách thăm dò một điểm cuối của gói thuê bao.

Để thiết lập một chủ đề Cloud Pub/Sub, bạn cần làm như sau:

  1. Đảm bảo bạn đáp ứng các Điều kiện tiên quyết của Cloud Pub/Sub.
  2. Thiết lập ứng dụng Cloud Pub/Sub.
  3. Xem lại giá của Cloud Pub/Sub, và bật tính năng thanh toán cho dự án trên Play Console.

  4. Tạo một chủ đề Cloud Pub/Sub trong Developer Console (dễ nhất), thông qua công cụ dòng lệnh (để sử dụng theo chương trình đơn giản) hoặc sử dụng Cloud Pub/Sub API. Xin lưu ý rằng Cloud Pub/Sub chỉ cho phép một số lượng chủ đề có hạn, vì vậy, việc sử dụng một chủ đề để nhận tất cả thông báo sẽ đảm bảo bạn không gặp phải vấn đề về khả năng mở rộng nếu ứng dụng của bạn trở nên phổ biến.

  5. Tạo một gói thuê bao trong Cloud Pub/Sub để cho Cloud Pub/Sub biết cách gửi thông báo.

  6. Cuối cùng, trước khi đăng ký nhận Thông báo đẩy, bạn cần cấp quyền cho tài khoản dịch vụ Thông báo đẩy (classroom-notifications@system.gserviceaccount.com) để đăng lên chủ đề của bạn.

Đăng ký ứng dụng của bạn để nhận thông báo

Sau khi có một chủ đề mà tài khoản dịch vụ thông báo đẩy của Classroom API có thể đăng lên, bạn có thể đăng ký nhận thông báo bằng phương thức registrations.create(). Phương thức registrations.create() xác thực rằng tài khoản dịch vụ thông báo đẩy có thể truy cập vào chủ đề Cloud Pub/Sub được cung cấp. Phương thức này sẽ không thành công nếu tài khoản dịch vụ thông báo đẩy không thể truy cập vào chủ đề; ví dụ: nếu chủ đề không tồn tại hoặc bạn chưa cấp quyền đăng cho chủ đề đó.

Ủy quyền

Giống như tất cả các lệnh gọi đến Classroom API, các lệnh gọi đến registrations.create() phải được uỷ quyền bằng mã uỷ quyền. Mã thông báo xác thực này phải bao gồm phạm vi Thông báo đẩy (https://www.googleapis.com/auth/classroom.push-notifications) và mọi phạm vi cần thiết để xem dữ liệu về thông báo đang được gửi.

  • Đối với nguồn cấp dữ liệu thay đổi danh sách, điều này có nghĩa là phạm vi Danh sách hoặc (lý tưởng nhất) biến thể chỉ có thể đọc của phạm vi đó (https://www.googleapis.com/auth/classroom.rosters.readonly hoặc https://www.googleapis.com/auth/classroom.rosters).
  • Đối với nguồn cấp dữ liệu thay đổi bài tập trên lớp, điều này có nghĩa là phiên bản "học viên" của phạm vi bài tập trên lớp hoặc (lý tưởng nhất) biến thể chỉ có thể đọc của phạm vi đó (https://www.googleapis.com/auth/classroom.coursework.students.readonly hoặc https://www.googleapis.com/auth/classroom.coursework.students).

Để thông báo được gửi, ứng dụng phải giữ lại một quyền sử dụng OAuth từ người dùng được uỷ quyền có các phạm vi bắt buộc. Nếu người dùng ngắt kết nối ứng dụng, thông báo sẽ ngừng. Xin lưu ý rằng hiện tại, tính năng uỷ quyền trên toàn miền không được hỗ trợ cho mục đích này. Nếu chỉ sử dụng quyền được uỷ quyền trên toàn miền để đăng ký nhận thông báo, bạn sẽ gặp lỗi @MissingGrant.

Nhận thông báo

Thông báo được mã hoá bằng JSON và chứa:

  • Tên của tập hợp chứa tài nguyên đã thay đổi. Đối với thông báo về các thay đổi trong danh sách, đây là courses.students hoặc courses.teachers. Đối với các thay đổi trong bài tập trên lớp, đây là courses.courseWork hoặc courses.courseWork.studentSubmissions.
  • Mã nhận dạng cho tài nguyên đã thay đổi, trong một bản đồ. Bản đồ này được thiết kế để khớp với các đối số với phương thức get của tài nguyên thích hợp. Đối với thông báo về các thay đổi trong danh sách, các trường courseId và userId sẽ được điền sẵn và có thể được gửi mà không cần sửa đổi đến courses.students.get() hoặc courses.teachers.get(). Tương tự, các thay đổi đối với tập hợp courses.courseWork sẽ có các trường courseId và id có thể được gửi mà không cần sửa đổi đến courses.courseWork.get() và các thay đổi đối với tập hợp courses.courseWork.studentSubmissions sẽ có các trường courseId, courseWorkId, và id có thể được gửi mà không cần sửa đổi đến courses.courseWork.studentSubmissions.get().

Đoạn mã sau đây minh hoạ một thông báo mẫu:

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

Thông báo cũng có một thuộc tính thông báo registrationId, chứa mã nhận dạng cho đăng ký đã gây ra thông báo. Bạn có thể sử dụng thuộc tính này với registrations.delete() để hủy đăng ký nhận thông báo.