Những giáo viên sử dụng cả Lớp học và các công cụ của bên thứ ba phải đối mặt với thách thức khi thiết lập khoá học và danh sách học viên trên nhiều nền tảng. Họ có thể thực hiện việc này theo cách thủ công, thông qua việc tải tệp CSV lên hoặc nhập từng email. Tuy nhiên, với API Lớp học, các công cụ của bên thứ ba có thể giảm khối lượng công việc của giáo viên bằng cách tích hợp với trường hợp sử dụng phổ biến nhất của API: nhập danh sách học viên.
Tính năng nhập danh sách học viên cho phép các nền tảng của bên thứ ba truy xuất siêu dữ liệu, giáo viên và học viên của một khoá học theo từng khoá học với quyền của giáo viên hoặc quản trị viên. Giáo viên có thể truy xuất thông tin chi tiết về các khoá học mà họ dạy, trong khi quản trị viên có quyền truy cập vào thông tin chi tiết của tất cả các khoá học trên toàn bộ miền. Tính linh hoạt này cho phép nhà phát triển dễ dàng đưa danh sách học viên trong Lớp học lên nền tảng của họ ở cấp độ từng giáo viên hoặc trên toàn bộ miền bằng cách sử dụng thông tin đăng nhập của quản trị viên.
Trước khi đi sâu vào thông tin chi tiết kỹ thuật về cách tích hợp tính năng nhập danh sách học viên, trước tiên, hãy xem xét một quy trình làm việc mẫu:
Trong ứng dụng của bên thứ ba, giáo viên chọn tuỳ chọn nhập Khoá học trong Lớp học Course.
Ứng dụng của bên thứ ba gọi phương thức
courses.listthông qua API Lớp học. Phương thức này sẽ trả về một JSON phản hồi với tất cả các khoá học của giáo viên.Từ phản hồi JSON, ứng dụng của bên thứ ba hiển thị tiêu đề của các khoá học của giáo viên để họ chọn một khoá học. Ứng dụng sẽ cần theo dõi mã khoá học để tiếp tục bước tiếp theo.
Với mã khoá học đã chọn, ứng dụng của bên thứ ba gọi các phương thức
students.listvàteachers.listrồi hiển thị tất cả tên trên trang web của ứng dụng để giáo viên xác nhận nhập.Sử dụng email được trả về trong JSON phản hồi
students.listvàteachers.list, ứng dụng của bên thứ ba mời người dùng tham gia khoá học mới nhập trên nền tảng của họ.
Đối với mỗi phương thức được đề cập trong quy trình làm việc, bạn có thể sử dụng Trình khám phá API để xem chính xác cách hoạt động của từng phương thức. Bạn cũng nên đọc trước các nội dung sau đây trước khi hoàn tất hướng dẫn này:
Bắt đầu
Trước khi triển khai thông tin cụ thể về tính năng nhập danh sách học viên trong Lớp học, bạn cần xác định thông tin về khoá học và người dùng mà bạn cần truy xuất thông qua API. Bạn có thể xem siêu dữ liệu Khoá học nào có trong tài liệu tham khảo, nhưng một số trường bắt buộc hoặc trường phổ biến cần thiết có thể được tóm tắt bên dưới:
| Trường | Sử dụng |
|---|---|
| id | Bắt buộc đối với các yêu cầu API truy xuất học viên hoặc giáo viên |
| name | Nên dùng để người dùng dễ sử dụng, tức là hiển thị trên trang web của bạn |
| ownerId | Bắt buộc khi nhập trên cơ sở toàn miền để xác định chính xác giáo viên chính của một khoá học |
Thông tin về khoá học này được truy xuất ở bước courses.list của quy trình làm việc ở trên. Trong yêu cầu này, bạn có thể chỉ định một số tham số yêu cầu. Mặc dù không có tham số nào là bắt buộc đối với phương thức này, nhưng có một số tham số nên dùng:
| Tham số | Sử dụng |
|---|---|
| courseState | Nếu không chỉ định, API sẽ trả về các khoá học thuộc cả 6 trạng thái khoá học. Bạn nên chỉ định ACTIVE để truy xuất các khoá học mà giáo viên hiện đang sử dụng. |
| pageSize | Đối với những giáo viên đang nhập khoá học của riêng họ, bạn nên chỉ định một pageSize nhỏ (dưới 10) để giảm thời gian phản hồi của lệnh gọi API. |
| pageToken | Bắt buộc nếu bạn đang sử dụng các yêu cầu được phân trang. |
| teacherId | Nên dùng vì quản trị viên miền thường dạy các khoá học. Nếu không chỉ định, yêu cầu sẽ trả về các khoá học cho giáo viên trên toàn bộ miền. |
| fields | Nên dùng để giảm thời gian phản hồi của lệnh gọi API. |
Sử dụng mã khoá học đã truy xuất trước đó, ứng dụng của bạn hiện có thể truy xuất danh sách học viên và giáo viên cùng dạy cho khoá học hoặc các khoá học đó. Mã khoá học này là tham số truy vấn bắt buộc duy nhất cho teachers.list và students.list, nhưng bạn cũng có thể cân nhắc chỉ định các tham số pageSize và fields để giảm thời gian phản hồi của các lệnh gọi API.
Bạn có thể tìm thấy tất cả các trường có sẵn cho tài nguyên
học viên
và giáo viên
trong tài liệu tương ứng. Hai trường được sử dụng phổ biến nhất và thường là bắt buộc là các trường trong trường profile field:
profile.name và profile.emailAddress.
| Trường | Sử dụng |
|---|---|
| profile.name | Nên dùng để người dùng dễ sử dụng, tức là hiển thị trên trang web của bạn |
| profile.emailAddress | Bắt buộc đối với các ứng dụng muốn xác định học viên một cách duy nhất |
Để truy xuất và sử dụng bất kỳ thông tin chi tiết nào về khoá học hoặc danh sách học viên này từ Lớp học, ứng dụng của bạn cần yêu cầu người dùng cấp quyền. Có 3 phạm vi bắt buộc để triển khai quy trình làm việc này:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Cung cấp quyền truy cập Chỉ đọc vào Khoá học trong Google Lớp học
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Cung cấp quyền truy cập Chỉ đọc vào danh sách học viên của Khoá học trong Google Lớp học (giáo viên và học viên)
- https://www.googleapis.com/auth/classroom.profile.emails
- Cung cấp quyền truy cập Đọc vào thuộc tính email của giáo viên và học viên
Đồng bộ hoá danh sách bằng thông báo Pub/Sub
Khi năm học tiến triển, danh sách học viên có thể thay đổi khi học viên bỏ hoặc thêm khoá học. Việc thêm thông báo Pub/Sub sẽ cho phép bạn đồng bộ hoá ứng dụng của bên thứ ba với danh sách học viên trong Lớp học. Để nhận thông báo, bạn hãy thiết lập một chủ đề Google Cloud Pub/Sub rồi đăng ký chủ đề đó với API Lớp học. Việc đăng ký này là một yêu cầu để Lớp học gửi dữ liệu từ nguồn cấp dữ liệu đã cho đến chủ đề đã cho. Nguồn cấp dữ liệu này sẽ là trình kích hoạt sự kiện để đồng bộ hoá lại với danh sách học viên trong Lớp học của giáo viên.
Việc sử dụng thông báo đẩy sẽ yêu cầu thêm một phạm vi mà bạn không phải gửi để xác minh:
- https://www.googleapis.com/auth/classroom.push-notifications
- Cho phép ứng dụng của bạn đăng ký mọi hoạt động thông báo đẩy
Để biết thêm thông tin chi tiết về cách tích hợp với thông báo đẩy trong Lớp học, hãy xem hướng dẫn Quản lý thông báo đẩy.