Những giáo viên sử dụng cả công cụ Lớp học và công cụ của bên thứ ba sẽ đối mặt với thách thức khi thiết lập khoá học và danh sách trên nhiều nền tảng. Bạn có thể làm 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 bớt 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 này: 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 của khoá học, giáo viên và học viên 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ộ một miền. Sự linh hoạt này cho phép nhà phát triển tích hợp liền mạch các danh sách trong Google Lớp học vào nền tảng của mình, cả ở 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 tìm hiểu chi tiết kỹ thuật về quy trình tích hợp nhập danh sách, hãy xem lại quy trình mẫu:
Trong ứng dụng của bên thứ ba, giáo viên sẽ chọn lựa chọn nhập một Khoá học trong 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 tệp JSON phản hồi kèm theo 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 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 thực hiện bước tiếp theo.
Với mã khoá học đã chọn, ứng dụng bên thứ ba sẽ gọi phương thức
students.listvàteachers.listvà 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 việc sử dụng các 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 công việc, bạn có thể sử dụng API Explorer để xem chính xác cách hoạt động của mỗi phương thức. Bạn cũng nên đọc trước khi đọc hết hướng dẫn này:
Bắt đầu
Trước khi triển khai các chi tiết cụ thể về tính năng nhập danh sách trong Lớp học, bạn cần xác định khoá học và thông tin người dùng cần truy xuất qua API. Bạn có thể xem siêu dữ liệu của Khoá học có trong Tài liệu tham khảo, nhưng bạn có thể tóm tắt một số trường bắt buộc hoặc cần thiế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 để dễ sử dụng cho người dùng, tức là đăng 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 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 các tham số yêu cầu nhất định. Mặc dù không bắt buộc phải sử dụng 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 không chỉ định, API sẽ trả về các khoá học theo cả 6 trạng thái của 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 yêu cầu được phân trang. |
| teacherId | Được đề xuất 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 này sẽ trả về các khoá học 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 của 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. Tuy nhiên, tương tự, 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 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. 2 trường thường được dùng thường xuyên và cần thiết là trong trường profile: profile.name và profile.emailAddress.
| Trường | Sử dụng |
|---|---|
| profile.name | Nên dùng để dễ sử dụng cho người dùng, tức là đăng trên trang web của bạn |
| profile.emailAddress | Bắt buộc đối với các ứng dụng muốn nhận dạng riêng học sinh |
Để 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 trong Lớp học, ứng dụng của bạn cần yêu cầu uỷ quyền từ người dùng. Có 3 (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
- Cấp quyền chỉ có thể đọc vào các Khoá học của Google Lớp học
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Cung cấp quyền truy cập Chỉ có thể đọc vào danh sách 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 diễn ra, danh sách có thể thay đổi khi học viên bỏ học hoặc thêm khoá học. Việc thêm thông báo Pub/Sub sẽ cho phép bạn luôn đồng bộ hoá ứng dụng bên thứ ba với hệ thống cửa hàng Lớp học. Để nhận thông báo, bạn cần thiết lập một chủ đề Google Cloud Pub/Sub, sau đó đăng ký chủ đề đó với API Lớp họ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 nhất định đến chủ đề nhất định. Nguồn cấp dữ liệu này sẽ là yếu tố kích hoạt sự kiện để đồng bộ hoá lại với danh sách trong Lớp học của giáo viên.
Khi sử dụng thông báo đẩy, bạn sẽ cần thêm một phạm vi nữa (bạn không cần gửi thông báo 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.