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

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

Bài viết này cung cấp thông tin tổng quan về khái niệm cùng với các 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 API Lớp học cho phép các ứng dụng sử dụng API Lớp học đăng ký nhận thông báo khi dữ liệu trong Lớp học thay đổi. Thông báo được gửi đến chủ đề Cloud Pub/Sub, thường trong vòng vài phút kể từ khi thay đổi diễn ra.

Để nhận thông báo đẩy, bạn cần thiết lập chủ đề Cloud Pub/Sub và cung cấp tên chủ đề đó khi tạo lượt đă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 đội hình cho khoá học 1234".
  • Đăng ký là một hướng dẫn đối với API Lớp học để 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 đăng ký cho nguồn cấp dữ liệu, chủ đề Cloud Pub/Sub của gói đăng ký đó sẽ nhận được thông báo từ nguồn cấp dữ liệu đó cho đến khi hết hạn. Gói đăng ký của bạn sẽ có hiệu lực trong một tuần, nhưng bạn có thể gia hạn bất cứ lúc nào trước khi gói đăng ký hết hạn bằng cách gửi một yêu cầu tương tự đến registrations.create().

Chủ đề Cloud Pub/Sub của bạn chỉ nhận được 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 gói đăng ký. Ví dụ: nếu người dùng thu hồi quyền trong ứng dụng của bạn hoặc bị xoá vai trò giáo viên, thì thông báo sẽ được gửi lâu hơn.

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

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

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

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

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

  1. Đảm bảo bạn đáp ứng Điều kiện tiên quyết về Cloud Pub/Sub.
  2. Thiết lập máy khách 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 Developer Console của bạn.

  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 cách có lập trình đơn giản) hoặc sử dụng API Cloud Pub/Sub. Xin lưu ý rằng Cloud Pub/Sub chỉ cho phép một số ít chủ đề. 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ề tỷ lệ nếu ứng dụng của bạn trở nên phổ biến.

  5. Tạo Gói thuê bao trong Cloud Pub/Sub để hướng dẫn Cloud Pub/Sub cách gửi thông báo của bạn.

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

LƯU Ý: Nếu bạn cấp quyền cho tài khoản dịch vụ Thông báo đẩy để phát hành lên chủ đề Cloud Pub/Sub của mình, thì những người dùng có thể yêu cầu từ dự án Developer Console của bạn sẽ có thể xác định rằng chủ đề đó tồn tại và đăng ký thông báo về chủ đề đó. Nhiều ứng dụng lưu trữ Mã ứng dụng khách OAuth ở phía máy khách, vì vậy, người dùng cuối có thể đưa ra yêu cầu từ dự án Developer Console của bạn. Nếu điều này đúng với bạn và bạn lo ngại về việc người dùng cuối gửi thông báo không mong muốn đến chủ đề Cloud Pub/Sub hoặc biết tên các chủ đề Cloud Pub/Sub mà bạn sử dụng cho thông báo đẩy, thì bạn nên cân nhắc việc đăng ký nhận thông báo đẩy của một dự án khác trên Developer Console.

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

Sau khi có chủ đề mà tài khoản dịch vụ thông báo đẩy của API Lớp học 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 phát hành cho chủ đề đó.

Ủy quyền

Giống như mọi lệnh gọi đến API Lớp học, các lệnh gọi đến registrations.create() phải được cấp quyền bằng mã thông báo 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à bất kỳ phạm vi nào 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, đây có nghĩa là phạm vi Roster hoặc (tốt nhất là) biến thể chỉ có thể đọc (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 khoá học, đó là các phiên bản "học viên" của phạm vi bài tập khoá học hoặc (tốt nhất là) biến thể chỉ có thể đọc (https://www.googleapis.com/auth/classroom.coursework.students.readonly hoặc https://www.googleapis.com/auth/classroom.coursework.students).

Để gửi thông báo, ứng dụng phải giữ lại lượt cấp OAuth từ người dùng được uỷ quyền trong phạm vi bắt buộc. Nếu người dùng ngắt kết nối ứng dụng, thì thông báo sẽ dừng lại. Xin lưu ý rằng hiện tại, chúng tôi không hỗ trợ việc uỷ quyền trên toàn miền cho mục đích này. Nếu bạn cố gắng đăng ký nhận thông báo chỉ bằng thẩm quyền được uỷ quyền trên toàn miền, 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à có 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 về danh sách, đây là courses.students hoặc courses.teachers. Đối với các thay đổi về bài tập trong khoá học, đây là courses.courseWork hoặc courses.courseWork.studentSubmissions.
  • Giá trị nhận dạng cho tài nguyên đã thay đổi trong một bản đồ. Bản đồ này được thiết kế để so khớp 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ề việc thay đổi danh sách, các trường courseId và userId sẽ được điền và có thể được gửi đến courses.students.get() hoặc courses.teachers.get(). Tương tự như vậy, các thay đổi đối với các trường khóa học.courseWork sẽ có các trường courseId và id có thể gửi không sửa đổi thành courses.courseWork.get() courseWorkIdvà các thay đổi đối với bộ sưu tập courseIdcourses.courseWork.get().idcourses.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ó thuộc tính tin nhắn registrationId, chứa giá trị nhận dạng cho lượt đăng ký đã tạo ra thông báo. Giá trị này có thể được dùng với registrations.delete() để huỷ đăng ký nhận thông báo.