Cấu trúc API

Hướng dẫn này cung cấp thông tin tổng quan về các thành phần chính tạo nên API Google Lớp học. API Google Lớp học bao gồm các tài nguyên và dịch vụ. Tài nguyên đại diện cho các thực thể trong Google Lớp học, chẳng hạn như một khoá học hoặc bài tập, còn các dịch vụ sẽ truy xuất và quản lý các tài nguyên này. Một số thực thể này có các thuộc tính bổ sung dành riêng cho API ngoài những thuộc tính có trong Lớp học. Các loại thực thể chính là:

Thực thể	Cách thể hiện trong Lớp học
Khoá học	Một lớp, chẳng hạn như "M. Toán học của Smith trong tiết 4".
Bí danh	Mã nhận dạng thay thế cho một khoá học.
Lời mời	Một phương thức để thêm người dùng vào một lớp.
Học viên	Một học viên trong lớp học.
Giáo viên	Một giáo viên trong lớp học.
Hồ sơ người dùng	Người dùng nói chung, ngoài ngữ cảnh học viên hoặc giáo viên.
CourseWork	Một bài tập trong lớp học.
StudentSubmissions	Bài tập của học viên cho một bài tập cụ thể, chẳng hạn như câu trả lời hoặc phiếu bài tập.
CourseWorkMaterials	Tài liệu dành cho học viên trong một lớp học.
Thông báo	Thông báo cho học viên trong một lớp học.
AddOnAttachment	Nội dung hoặc hoạt động trong bài tập hoặc tài liệu thường xuất hiện dưới dạng iframe được nhúng.
Chủ đề	Một nhóm hình ảnh gồm các bài tập và tài liệu trong một lớp học.
Gói đăng ký	Hướng dẫn gửi thông báo đến ứng dụng của bạn về các thay đổi đối với dữ liệu, chẳng hạn như danh sách lớp học.

Hầu hết các tài nguyên đều có các phương thức dịch vụ cho các thao tác tiêu chuẩn như đọc, cập nhật và xoá các thực thể của tài nguyên. Một số tài nguyên cũng có các phương thức tuỳ chỉnh cho các thao tác khác, chẳng hạn như sửa đổi danh sách học viên được giao một bài tập cụ thể.

Để biết thông tin chi tiết về các tài nguyên và phương thức API, hãy tham khảo Tài liệu tham khảo về API Lớp học.

Tổng quan về mối quan hệ tài nguyên

• Khoá học là đối tượng dữ liệu cơ bản trong Google Lớp học.
• Tên đại diện được dùng làm giá trị nhận dạng thay thế cho Courses.
• Lời mời được dùng để mời Hồ sơ người dùng trở thành Giáo viên hoặc Học viên trong Course, nhưng quản trị viên miền Google Workspace for Education cũng có thể thêm người dùng trực tiếp.
• Giáo viên tạo Mục trong bảng tin và chia sẻ các mục đó với học viên trong khoá học của mình. Các loại mục có thể xuất hiện trong luồng là Coursework (Bài tập), CourseWorkMaterials (Tài liệu bài tập) và Announcements (Thông báo). CourseWork và CourseWorkMaterials có thể được sắp xếp một cách trực quan thành các Chủ đề và có thể chứa AddOnAttach. Học viên gửi StudentSubmissions cho CourseWork của họ.
• Nhà phát triển có thể tạo Lượt đăng ký để nhận thông báo khi một số dữ liệu này thay đổi.

Google Lớp học được cung cấp cho các miền đăng ký Google Workspace for Education. Một miền trong bối cảnh Lớp học thường đại diện cho một học khu. Bạn có thể tạo một miền thử nghiệm Google Workspace for Education cho mục đích phát triển. Điều này cho phép bạn kiểm soát phiên bản chính thức của Lớp học mà không ảnh hưởng đến người dùng thực.

Khoá học và bí danh

Courses đại diện cho một lớp, chẳng hạn như "M. môn toán học kỳ 4 của Smith", và các giáo viên được chỉ định, danh sách học sinh và siêu dữ liệu. Mỗi khoá học được xác định bằng một mã nhận dạng duy nhất do máy chủ chỉ định. Tài nguyên Course đóng gói cụ thể tất cả siêu dữ liệu về khoá học, chẳng hạn như tên, nội dung mô tả, địa điểm và thời gian. Danh sách lớp học được quản lý thông qua các tài nguyên Học viên, Giáo viên và Lời mời cũng như các phương thức của các tài nguyên này.

Aliases là giá trị nhận dạng thay thế cho một lớp có thể được liên kết với một khoá học và được dùng thay cho mã nhận dạng duy nhất. Mỗi bí danh tồn tại trong một không gian tên hạn chế những người có thể tạo và xem bí danh đó. Hỗ trợ 2 không gian tên:

• Miền: Không gian tên miền hữu ích cho việc tạo các bí danh mà tất cả người dùng cần truy cập, nhưng không dành riêng cho bất kỳ chương trình nào. Ví dụ: bạn nên tạo trang thông tin thay thế cho một khoá học, chẳng hạn như MATH 127 và COMSCI 127, trong không gian tên miền. Chỉ quản trị viên miền mới có thể tạo bí danh trong không gian tên miền, nhưng tất cả người dùng trong miền đều có thể nhìn thấy.
• Dự án dành cho nhà phát triển: Không gian tên dự án của nhà phát triển rất hữu ích trong việc quản lý các bí danh dành riêng cho một ứng dụng. Ví dụ: một ứng dụng sử dụng giá trị nhận dạng thay thế cho các khoá học có thể tạo bí danh để liên kết giá trị nhận dạng của ứng dụng với các khoá học trên Lớp học. Các bí danh được tạo trong không gian tên này được liên kết với một Bảng điều khiển API của Google cụ thể. Mọi người dùng của một ứng dụng đều có thể tạo và xem bí danh trong không gian tên cho dự án nhà phát triển của ứng dụng đó.

Để biết thêm thông tin về cách quản lý siêu dữ liệu và bí danh của khoá học, hãy xem bài viết Quản lý khoá học.

Danh sách lớp học và người dùng

Students và Teachers là các mối liên kết cụ thể giữa hồ sơ người dùng và một khoá học, đại diện cho vai trò của người dùng đó trong khoá học. Chỉ định học viên và giáo viên không phải là giáo viên trên toàn cầu: người dùng có thể được chỉ định làm giáo viên cho một khoá học và một học viên trong một khoá học khác. Chức danh "học viên" hoặc "giáo viên" đại diện cho một nhóm quyền cho một người dùng cụ thể trong một khoá học cụ thể.

Sinh viên

Tài nguyên Student đại diện cho một người dùng đã đăng ký làm học viên trong một khoá học cụ thể.

Học viên được phép xem thông tin chi tiết về khoá học và giáo viên của khoá học đó.

Giáo viên

Tài nguyên Teacher đại diện cho một người dùng dạy một khoá học cụ thể.

Giáo viên được phép xem và thay đổi thông tin chi tiết về khoá học, xem giáo viên và học viên, cũng như quản lý các giáo viên và học viên khác.

Invitations và các phương thức liên quan của lớp này cung cấp một cách thuận tiện để thêm học viên và giáo viên vào các khoá học. Việc tạo lời mời cho phép người dùng chọn tham gia hay không tham gia một khoá học, thay vì bạn trực tiếp thêm họ thông qua tài nguyên dành cho giáo viên và học viên.

UserProfiles biểu thị mối liên kết đến hồ sơ miền của người dùng được xác định bằng mã nhận dạng duy nhất hoặc địa chỉ email của người dùng do Directory API trả về. Người dùng hiện tại cũng có thể tham chiếu đến mã nhận dạng của riêng họ bằng cách sử dụng ký hiệu viết tắt "me".

Bạn cũng có thể sử dụng dịch vụ UserProfiles để quản lý và mời Guardians – đây là mối liên kết giữa học viên và người giám hộ. Người giám hộ trong Lớp học có quyền truy cập vào một số thông tin của học sinh, chẳng hạn như bài tập của học sinh.

Để biết thêm thông tin về cách quản lý danh sách, hãy xem phần Quản lý giáo viên và học viên.

Bài tập và bài nộp của học viên

Mục CourseWork đại diện cho một nhiệm vụ được giao cho một nhóm học viên trong một khoá học. Tệp này chứa các thông tin chi tiết như nội dung mô tả, ngày đến hạn và tài liệu cũng như siêu dữ liệu như thời gian tạo. Tài liệu bao gồm tiêu đề, hình thu nhỏ và URL, cũng như một giá trị nhận dạng có thể được sử dụng với các API thích hợp (tức là Drive, YouTube).

Mục CourseWork mô tả một trong các loại tác vụ sau:

• Một bài tập mà học viên hoàn thành bằng cách nộp bảng tính hoặc các tệp đính kèm khác.
• Câu hỏi dạng câu trả lời ngắn hoặc câu hỏi trắc nghiệm.

Bài tập của học viên có một mục CourseWork được biểu thị bằng StudentSubmission. Thành phần này bao gồm một phản hồi và siêu dữ liệu bổ sung, chẳng hạn như trạng thái và điểm được chỉ định.

Nội dung của StudentSubmission phụ thuộc vào loại mục CourseWork tương ứng:

• Trang tính và tệp đính kèm được gửi cho một bài tập, bao gồm cả tiêu đề, hình thu nhỏ và URL, cũng như giá trị nhận dạng có thể được sử dụng với các API thích hợp như Drive hoặc YouTube.
• Câu trả lời cho câu hỏi dạng câu trả lời ngắn hoặc câu hỏi trắc nghiệm.

Để biết thêm thông tin về cách quản lý bài tập và bài nộp của học viên, hãy xem bài viết Quản lý bài tập trên lớp.

Tài liệu và thông báo về bài tập

Tương tự như CourseWork, CourseWorkMaterials đại diện cho nội dung được giao cho một nhóm học viên trong một khoá học, với thông tin chi tiết như tiêu đề và nội dung mô tả, cùng với tài liệu. Tuy nhiên, không giống như CourseWork, CourseWorkMaterials không yêu cầu học viên gửi bất kỳ cấu phần phần mềm nào. Do đó, không có ngày đến hạn và StudentSubmissions không tồn tại đối với CourseWorkMaterials. Ví dụ: giáo viên có thể sử dụng CourseWorkMaterials để đăng tài liệu đọc được đề xuất, đề cương hoặc nội quy lớp học.

Announcements cũng đại diện cho nội dung được chia sẻ với một nhóm học viên, nhưng không có thông tin chi tiết như tiêu đề và không thể được sắp xếp theo Topics như CourseWork hoặc CourseWorkMaterials. Giáo viên có thể sử dụng các thông báo này để thông báo nhắc nhở hoặc thông báo cho lớp học.

Chủ đề

Topics được dùng để sắp xếp trực quan CourseWork và CourseWorkMaterials trong một lớp. Ví dụ: bạn có thể dùng các mục này để nhóm các bài tập thành "không bắt buộc" và "bắt buộc" hoặc "đơn vị 1" và "đơn vị 2".

Tiện ích bổ sung dành cho Lớp học

Tiện ích bổ sung là giao diện người dùng do nhà phát triển phân phát và phần phụ trợ thường hiển thị trong iframe. Tiện ích bổ sung xuất hiện dưới dạng tệp đính kèm trên một mục trong luồng. Mục phát trực tuyến có thể là Announcements, CourseWork hoặc CourseWorkMaterials bất kỳ. Tiện ích bổ sung được đính kèm bằng AddOnAttachment.

Tệp đính kèm tiện ích bổ sung có thể là hoạt động hoặc nội dung.

• Tệp đính kèm của hoạt động yêu cầu học viên hoàn thành và nộp một bài nộp riêng lẻ. Ví dụ: bài kiểm tra, bản vẽ hoặc trò chơi. Bạn có thể chọn chấm điểm cho bài nộp của một hoạt động.
• Tài liệu đính kèm về nội dung không yêu cầu học viên gửi. Học viên không cần nộp tệp đính kèm và tệp đính kèm này sẽ không được chấm điểm. Ví dụ: ảnh, bài viết và video.

Xem hướng dẫn phát triển tiện ích bổ sung để biết thêm thông tin.

Đăng ký

Các ứng dụng có thể đăng ký nhận thông báo khi một số dữ liệu nhất định thay đổi trong Google Lớp học. Ví dụ: khi danh sách lớp học của một khoá học được cập nhật. Registrations đưa ra hướng dẫn gửi các thông báo này đến ứng dụng của bạn.

Hãy xem hướng dẫn về thông báo đẩy để tìm hiểu thêm.