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 sẽ gặp phải thách thức khi thiết lập các khoá học và danh sách lớp học trên nhiều nền tảng. Bạn có thể thực hiện việc này theo cách thủ công, thông qua tính năng 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 tải 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 lớp.
Tính năng nhập danh sách cho phép các nền tảng 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 bằng 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ọ giảng dạy, trong khi quản trị viên có quyền truy cập vào thông tin chi tiết về tất 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 đưa danh sách lớp học vào nền tảng của họ một cách liền mạch ở cả cấp giáo viên cá nhân hoặc trên toàn bộ miền bằng cách sử dụng thông tin xác thực của quản trị viên.
Trước khi đi sâu vào thông tin kỹ thuật về cách tích hợp tính năng nhập danh sách, trước tiên, hãy xem xé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 trên Lớp học.
Ứng dụng bên thứ ba gọi phương thức
courses.listthông qua API Lớp học. API này sẽ trả về một phản hồi JSON có tất cả các khoá học của giáo viên.Từ phản hồi json, ứng dụng bên thứ ba sẽ hiển thị tên 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 bên thứ ba sẽ gọi các phương thức
students.listvàteachers.list, đồng thờ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.Bằng cách sử dụng các email được trả về trong json phản hồi
students.listvàteachers.list, ứng dụng bên thứ ba sẽ 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 bài viết sau trước khi hoàn thành hướng dẫn này:
Bắt đầu
Trước khi triển khai thông tin cụ thể về việc nhập danh sách lớp học trên Lớp học, bạn cần xác định những khoá học và thông tin 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 về khoá học có sẵn 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 dưới đây:
| 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 |
| tên | 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 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 công 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 nhất định. Mặc dù không có tham số nào bắt buộc đối với phương thức này, nhưng bạn nên sử dụng một số tham số sau:
| Thông số | Sử dụng |
|---|---|
| courseState | Nếu bạn 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 đang sử dụng. |
| pageSize | Đối với những giáo viên đang nhập các khoá học của riêng mình, 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 phân trang. |
| teacherId | Bạn nên chọn vai trò này vì quản trị viên miền thường là người dạy các khoá học. Nếu bạn không chỉ định, yêu cầu này sẽ trả về các khoá học dành cho giáo viên trên toàn bộ miền. |
| fields | Bạn nên giảm thời gian phản hồi của lệnh gọi API. |
Bằng cách sử dụng mã khoá học đượ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à người 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 nên 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ể xem tất cả các trường hiện có 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 thường được sử dụng nhất và thường bắt buộc phải có nằm trong trường profile: 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 riêng biệ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 lớp học trong Lớp học, ứng dụng của bạn sẽ cần yêu cầu người dùng uỷ quyền. Có 3 (3) phạm vi bắt buộc để triển khai quy trình công việc này:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Cấp quyền Chỉ có thể đọc đối với Khoá học trên Google Lớp học
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Cấp quyền Chỉ có thể đọc đối với danh sách học viên của các khoá học trên Google Lớp học (giáo viên và học viên)
- https://www.googleapis.com/auth/classroom.profile.emails
- Cấp quyền Đọc đối với thuộc tính email của giáo viên và học viên
Đồng bộ hoá danh sách với thông báo Pub/Sub
Khi năm học trôi qua, danh sách lớp học 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 lớp học. Để nhận thông báo, bạn thiết lập một chủ đề Google Cloud Pub/Sub, sau đó đăng ký chủ đề đó bằng API Lớp học. Lượt đă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 lớp học của giáo viên.
Để sử dụng thông báo đẩy, bạn cần thêm một phạm vi khác (không bắt buộc 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ý bất kỳ hoạt động thông báo đẩy nào
Để biết thêm thông tin chi tiết về cách tích hợp với thông báo đẩy của Lớp học, hãy xem Hướng dẫn quản lý thông báo đẩy.