Người dùng của bạn có đang sử dụng Lớp học với Google Meet không? Hãy tham khảo bài viết hướng dẫn nhanh về Apps Script để biết cách điểm danh học viên trong các khóa học của Google Meet.

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 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 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 trên Lớp học

Tính năng thông báo đẩy 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. Các thông báo sẽ được gửi đến một chủ đề Cloud Pub/Sub, thường là trong vòng vài phút thay đổi.

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

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

  • Đích là nơi gửi thông báo.
  • Nguồn cấp dữ liệu là loại thông báo mà ứng dụng bên thứ ba có thể đăng ký. Ví dụ: "giá trị thay đổi của khóa học 1234".
  • Đăng ký là một hướng dẫn tớ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.

Khi bạn tạo một gói đăng ký cho nguồn cấp dữ liệu, chủ đề Cloud Pub/Sub của nhà đă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. Đăng ký của bạn sẽ kéo dài một tuần, nhưng bạn có thể gia hạn đăng ký bất kỳ lúc nào trước khi đăng ký hết hạn bằng cách gửi yêu cầu đồng ý đến registrations.create().

Chủ đề Cloud Pub/Sub của bạn chỉ nhận được các thông báo về những tài nguyên bạn có thể xem bằng thông tin đăng nhập 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 của ứng dụng của bạn hoặc bị xóa khỏi vai trò giáo viên, thông báo sẽ được gửi dài hơn.

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

API Lớp học hiện cung cấp ba 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 đối với miền. Nguồn cấp 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 khóa học trong miền đó.
  • Mỗi khóa học sẽ có một nguồn cấp dữ liệu thay đổi đối với khóa 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 các khóa học trong khóa học đó.
  • Mỗi khóa học có một nguồn cấp dữ liệu thay đổi bài tập khóa học cho khóa học. Nguồn cấp dữ liệu này sẽ hiển thị thông báo khi bất kỳ đối tượng nào gửi bài tập hoặc khóa học mà học viên đã gửi được tạo hoặc sửa đổi trong khóa học đó.

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

Các 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 các nội dung hấp dẫn trên web hoặc bằng cách thăm dò điểm cuối của gói đăng ký.

Để 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 về 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 Developer Console của bạn.
  4. Tạo chủ đề Cloud Pub/Sub trong Bảng điều khiển dành cho nhà phát triển (cách dễ nhất), qua công cụ dòng lệnh (đối với phương thức có lập 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ủ đề giới hạn, vì vậy, việc sử dụng một chủ đề để nhận tất cả thông báo đảm bảo bạn sẽ 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ở thành phổ biến.

  5. Tạo một gói đăng ký 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 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 quyền xuất bản tài khoản dịch vụ Thông báo đẩy vào chủ đề Cloud Pub/Sub, những người dùng có thể yêu cầu dự án Bảng điều khiển dành cho nhà phát triển của bạn sẽ có thể xác định rằng chủ đề đó đã tồn tại và đăng ký{ 101}thông báo về cuộc trò chuyện đó. Nhiều ứng dụng lưu trữ Mã ứng dụng khách OAuth ở phía máy khách, để người dùng cuối có thể gửi 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 điều này đúng với bạn và quan 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 của bạn 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 xem xét đăng ký nhận thông báo đẩy từ một dự án Bảng điều khiển dành cho nhà phát triển khác.

Đăng ký nhận đơn đăng ký 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 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 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 không thành công nếu tài khoản dịch vụ thông báo đẩy không thể tiếp cận chủ đề; ví dụ: nếu chủ đề không tồn tại hoặc bạn chưa cấp quyền xuất bả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 ủy quyền bằng mã thông báo ủy 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 bắt buộc để 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 đội hình, đ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 (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 của khóa học, điều này có nghĩa là các phiên bản của "học viên" trong phạm vi bài tập của khóa học hoặc (tốt nhất là) biến thể chỉ đọc (https://www.googleapis.com/auth/classroom.coursework.students.readonly hoặc https://www.googleapis.com/auth/classroom.coursework.students).

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

Đang nhận thông báo

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

  • Tên của tập hợp chứa tài nguyên đã thay đổi. Để biết thông báo về các thay đổi đối với đội hình, đây là courses.students hoặc courses.teachers. Đối với các thay đổi về bài tập, khóa học sẽ 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. Để thông báo về các thay đổi đối với đội hình, các trường courseIduserId sẽ được điền sẵn và có thể gửi chưa được sửa đổi đến course..students.get() hoặc courses.teachers.get(). Tương tự, các thay đổi đối với bộ sưu tập của course.courseWork sẽ có các trường courseIdid có thể được đưa vào khóa học courses.courseWork.get() và những thay đổi đối với khóa học.courseWork.studentSubmissions sẽ có courseId, courseWorkId, và trường id có thể được gửi chưa được sửa đổi vào courses.courseWork.studentSubmissions.get().

Đoạn mã sau đây minh họa 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 của gói đăng ký đã gây ra thông báo. Bạn có thể sử dụng thuộc tính này để sử dụng với registrations.delete() để hủy đăng ký nhận thông báo.