Hiện tại, các nhà phát triển đã có thể sử dụng rộng rãi tiện ích bổ sung của Google Lớp học! Vui lòng xem tài liệu về tiện ích bổ sung để biết thêm thông tin.

Trang này được dịch bởi Cloud Translation API.

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 bộ sưu tậ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 thay đổi.

Để nhận thông báo đẩy, bạn cần thiết lập một chủ đề trên Cloud Pub/Sub và cung cấp tên của chủ đề đó khi tạo một 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:

Đí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ý. Ví dụ: "thay đổi danh sách cho khoá học 1234".
Gói đăng ký là một hướng dẫn cho API Lớp học để phân phối thông báo từ một nguồn cấp dữ liệu cụ thể đến một đích đến.

Sau khi bạn tạo một lượt đăng ký cho một nguồn cấp dữ liệu, chủ đề Cloud Pub/Sub của lượt đă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. Quá trình đăng ký 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 gửi một yêu cầu giống hệt nhau đến registrations.create().

Chủ đề Cloud Pub/Sub của bạn chỉ nhận được thông báo về các 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 một lượt đăng ký. Ví dụ: nếu người dùng thu hồi quyền khỏi ứ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 thay đổi về danh sách lớp học 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 cũng như rời khỏi các khoá học trong miền đó.
Mỗi khoá học đều có nguồn cấp dữ liệu thay đổi về danh sách lớp học 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 cũng như rời khỏi khoá học trong khoá học đó.
Mỗi khoá học đều có nguồn cấp dữ liệu thay đổi về bài tập trong 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 nào trong khoá học hoặc đối tượng bài tập do học viên nộp đượ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 qua webhook 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:

Hãy đả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 lại giá Cloud Pub/Sub và bật tính năng thanh toán cho dự án Developer Console của bạn.
Tạo chủ đề Cloud Pub/Sub trong Developer Console (dễ nhất), thông qua công cụ dòng lệnh (để sử dụng theo phương thứ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ố 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 gói thuê bao trong Cloud Pub/Sub để cho Cloud Pub/Sub biết cách phân phối thông báo.
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) để phát hành lên chủ đề của bạn.

LƯU Ý: Nếu bạn cấp cho tài khoản dịch vụ Thông báo đẩy quyền phát hành lên chủ đề Cloud Pub/Sub, thì những người dùng có thể đưa ra yêu cầu từ dự án trong Developer Console sẽ có thể xác định rằng chủ đề đó tồn tại và đăng ký nhận 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 Bảng điều khiển dành cho nhà phát triển của bạn. Nếu trường hợp này xảy ra với bạn và bạn lo ngại người dùng cuối sẽ gửi thông báo không mong muốn đến chủ đề Cloud Pub/Sub hoặc biết tên của 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 đăng ký thông báo đẩy từ một dự án khác trong Developer Console.

Đă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ể phát hành, bạn có thể đăng ký nhận thông báo bằng cách sử dụng phương thức registrations.create(). Phương thức registrations.create() xác thực rằng chủ đề trên Cloud Pub/Sub có thể truy cập được bằng tài khoản dịch vụ thông báo đẩy. 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 cho tài khoản đó quyền phát hành 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ề thông báo nà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 (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 về bài tập trong khoá học, đ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 trong khoá học hoặc (tốt nhất là) biến thể chỉ có thể đọc của phạm vi bài tập đó (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 một khoản cấp phé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 với ứng dụng, thông báo sẽ ngừng. Xin lưu ý rằng hiện tại, chúng tôi không hỗ trợ việc uỷ quyền quyền trên toàn miền cho mục đích này. Nếu cố gắng đăng ký nhận thông báo chỉ bằng 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à 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, giá trị này là courses.students hoặc courses.teachers. Đối với các thay đổi về bài tập trong khoá học, giá trị nà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ế để 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ề các thay đổi đối với danh sách lớp học, 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ó 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. Bạn có thể sử dụng thuộc tính này với registrations.delete() để huỷ đăng ký khỏi thông báo.