Bạn có thể sử dụng các phương thức trên 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 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 thay đổi trong Lớp học. Thông báo được gửi đến một chủ đề Cloud Pub/Sub, 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 một gói đă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 dùng trong tài liệu này:
- Đích đến là nơi thông báo được gửi đến.
- 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ý nhận. Ví dụ: "thay đổi danh sách cho khoá học 1234".
- Đăng ký là một chỉ dẫn cho 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 một chế độ đăng ký cho nguồn cấp dữ liệu, chủ đề Cloud Pub/Sub của chế độ đă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. Bạn có thể đăng ký trong 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 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 đăng nhập mà bạn cung cấp khi tạo một lượt đă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 gửi nữa.
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 đều có một nguồn cấp dữ liệu roster changes for domain (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 đều có một nguồn cấp dữ liệu roster changes for course (thay đổi danh sách cho khoá học), nguồn cấp dữ liệu này sẽ hiển thị thông báo khi học viên và giáo viên tham gia và rời khỏi khoá học đó.
- Mỗi khoá học đều có một nguồn cấp dữ liệu course work changes for course (thay đổi về bài tập trên lớp của khoá học). Nguồn cấp dữ liệu này sẽ hiển thị thông báo khi có bất kỳ bài tập trên lớp hoặc đối tượng bài tập đã nộp nào của học viên được tạo hoặc sửa đổi trong khoá học đó.
Thiết lập một 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 một webhook hoặc bằng cách thăm dò một điểm cuối đăng ký.
Để thiết lập một chủ đề Cloud Pub/Sub, bạn cần làm như sau:
- Đảm bảo bạn đáp ứng Các điều kiện tiên quyết của Cloud Pub/Sub.
- Thiết lập một ứng dụng Cloud Pub/Sub.
- Xem giá của Cloud Pub/Sub và bật tính năng thanh toán cho dự án trên Developer Console.
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 bằng cách sử dụng API Cloud Pub/Sub. 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ề việc mở rộng quy mô nếu ứng dụng của bạn trở nên phổ biến.
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 cho bạn.
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) để xuất bản vào 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 API Lớp học có thể xuất bả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 truy cập được vào chủ đề; ví dụ: nếu chủ đề không tồn tại hoặc bạn chưa cấp cho tài khoản đó quyền xuất bản trên chủ đề đó.
Ủy quyền
Giống như tất cả các lệnh gọi đến API Lớp học, 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ề những 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 là) biến thể chỉ đọc của danh sách (
https://www.googleapis.com/auth/classroom.rosters.readonlyhoặchttps://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 của phạm vi đó (
https://www.googleapis.com/auth/classroom.coursework.students.readonlyhoặchttps://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 truy cập 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 xuất hiện. 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 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à có chứa:
- Tên của bộ sưu tập chứa tài nguyên đã thay đổi. Đối với thông báo về các thay đổi đối với danh sách, đây là
courses.studentshoặccourses.teachers. Đối với các thay đổi về bài tập trong khoá học, giá trị này làcourses.courseWorkhoặccourses.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ế để so khớp các đối số với phương thức
getcủa tài nguyên thích hợp. Đối với thông báo về các thay đổi đối với danh sách, các trườngcourseIdvàuserIdsẽ đượ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 bộ sưu tập courses.courseWork sẽ có các trườngcourseIdvàidcó thể được gửi mà không cần sửa đổi đến courses.courseWork.get() và các thay đổi đối với bộ sưu tập courses.courseWork.studentSubmissions sẽ có các trườngcourseId,courseWorkIdvàidcó 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ó thuộc tính thông báo registrationId, chứa giá trị nhận dạng cho lượt đăng ký gây ra thông báo. Giá trị nhận dạng này có thể dùng với registrations.delete() để huỷ đăng ký nhận thông báo.