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 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 việc sử dụng 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 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.
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 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ọ 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ả các khoá học trên toàn bộ miền. Nhờ tính linh hoạt này, các nhà phát triển có thể dễ dàng tích hợp danh sách lớp học trên Classroom vào 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 các chi tiết kỹ thuật về cách tích hợp tính năng nhập danh sách có thể diễn ra, trước tiên, hãy xem một quy trình ví dụ:
Trong ứng dụng bên thứ ba, giáo viên chọn nhập một 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. Phương thức này sẽ trả về một JSON phản hồi có tất cả các khoá học của giáo viên.Trong phản hồi json, ứng dụng bên thứ ba sẽ hiển thị tiêu đề 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 email được trả về trong các tệp 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 API Explorer để xem chính xác cách thức hoạt động của từng phương thức. Bạn cũng nên đọc trước những 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 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 nào của Khoá học có trong Tài liệu tham khảo, nhưng một số trường bắt buộc hoặc trường thường dùng 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 |
| 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 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 nhất định. 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 một số tham số nên dùng là:
| 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 hiện đang sử dụng. |
| pageSize | Đối với những giáo viên nhập 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 làm như vậy vì quản trị viên miền thường dạy các khoá học. Nếu bạn 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 giảm thời gian phản hồi của lệnh gọi API. |
Giờ đây, bằng cách sử dụng các mã khoá học đã truy xuất trước đó, ứng dụng của bạn có thể truy xuất danh sách học viên và người cùng dạy cho (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 việ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 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 thường được sử dụng nhất và thường là bắt buộc cần thiết 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 những ứ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 nào trong số này 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 cho phép. Bạn cần có 3 phạm vi để triển khai quy trình này:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Cung cấp quyền Chỉ đọc đối với Khoá học trên Google Lớp học
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Cung cấp quyền Chỉ đọc cho danh sách 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
- Cung cấp quyền Đọc cho 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 diễn ra, danh sách 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ẽ giúp bạn đồng bộ hoá ứng dụng bên thứ ba với danh sách lớp học trong Lớp học. Để nhận thông báo, bạn thiết lập một chủ đề Google Cloud Pub/Sub rồi đăng ký chủ đề đó bằng Classroom API. Việc đăng ký này là 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à các sự kiện kích hoạt để đồ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 sẽ cần thêm một phạm vi nữa và không cần gửi phạm vi này để 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 của Lớp học, hãy xem hướng dẫn Quản lý thông báo đẩy của chúng tôi.