Tài nguyên 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. Google Classroom API bao gồm 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ư khoá học hoặc bài tập, đồng thời các dịch vụ sẽ truy xuất và quản lý những tài nguyên này. Ngoài những thuộc tính có trong Lớp học, một số thực thể này còn có các thuộc tính bổ sung dành riêng cho API. Các loại thực thể chính là:

Thực thể	Phần hiển thị trong Lớp học
Khoá học	Một lớp học, chẳng hạn như "M. Toán tiết 4 của cô Smith".
Tên thay thế	Mã nhận dạng thay thế của một khoá học.
Lời mời	Cách thêm người dùng vào một lớp học.
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	Một người dùng nói chung, không phải là học viên hay giáo viên.
CourseWork	Một bài tập trong lớp học.
StudentSubmissions	Bài làm 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 bài tập và tài liệu trực quan trong một lớp học.
Đă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 trong 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ó 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ề Classroom API.

Tổng quan về mối quan hệ giữa các 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 thay thế đượ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 một Course, nhưng quản trị viên miền Google Workspace for Education cũng có thể thêm trực tiếp người dùng.
• Giáo viên tạo mục trên Bảng tin và chia sẻ các mục đó với học viên trong khoá học của họ. Các loại mục có thể có trong luồng là Coursework, CourseWorkMaterials và Announcements. CourseWork và CourseWorkMaterials có thể được sắp xếp trực quan thành Topics (Chủ đề) và có thể chứa AddOnAttachments (Tệp đính kèm bổ sung). Học viên gửi StudentSubmissions cho CourseWork của mình.
• Nhà phát triển có thể tạo Registration (Đă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 những miền đăng ký Google Workspace for Education. 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. Miền này cho phép bạn kiểm soát một phiên bản sản xuất 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. Toán học tiết 4 của Smith", cùng với giáo viên được chỉ định, danh sách học viên 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 đặc biệt bao gồm tất cả siêu dữ liệu về khoá học, chẳng hạn như tên, nội dung mô tả, vị trí và thời gian. Danh sách khoá 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 chúng.

Aliases là giá trị nhận dạng thay thế cho một lớp học 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 biệt hiệu đều 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 biệt hiệu đó. Hai không gian tên được hỗ trợ:

• Miền: Không gian tên miền rất hữu ích khi tạo các bí danh mà tất cả người dùng đều cần có quyề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 các mục 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 bí danh.
• Dự án dành cho nhà phát triển: Không gian tên dự án dành cho nhà phát triển rất hữu ích trong việc quản lý các biệt hiệu 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 biệt hiệu để 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 biệt hiệu được tạo trong không gian tên này sẽ được liên kết với một Google API Console cụ thể. Mọi người dùng ứng dụng đều có thể tạo và xem các bí danh trong không gian tên cho dự án của nhà phát triển ứng dụng đó.

Để biết thêm thông tin về cách quản lý siêu dữ liệu và biệt hiệu 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, thể hiện vai trò của người dùng đó trong khoá học. Việc chỉ định học viên và giáo viên không phải là thông tin chung: một người dùng có thể được chỉ định là giáo viên của một khoá học và là học viên của một khoá học khác. Chỉ định "học viên" hoặc "giáo viên" là một nhóm quyền của một người dùng cụ thể trong một khoá học cụ thể. Một khoá học có thể có nhiều giáo viên hoặc không có học viên nào. Giáo viên và học viên có thể được thêm vào hoặc xoá khỏi khoá học bất cứ lúc nào.

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ý giáo viên và học viên khác.

Invitations và các phương thức liên kết của chúng 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. Khi tạo lời mời, người dùng có thể chọn tham gia hoặc không tham gia 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 đại diện cho mối liên kết đến hồ sơ miền của người dùng như đượ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 chính họ bằng cách dùng ký hiệu viết tắt "me".

Bạn cũng có thể 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 viên, chẳng hạn như bài tập của học viên.

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

Mục trong luồng

Mục trong luồng là những phần nội dung được đăng và chia sẻ với các thành viên của khoá học. Nhà phát triển và giáo viên có thể tạo 3 loại mục trên luồng: Announcement, CourseWork và CourseWorkMaterial.

Giáo viên tạo Announcements ở đầu trang Bảng tin trong giao diện người dùng của Lớp học. Giáo viên tạo CourseWork và CourseWorkMaterials bằng cách nhấp vào nút Tạo trong thẻ Bài tập trên lớp. Nhà phát triển có thể tạo tất cả các loại mục trên luồng theo phương thức lập trình thông qua API Lớp học.

Sau đây là những điều đúng về các mục trong luồng phát:

• Tất cả các mục trên luồng đều có thể chứa tài liệu bổ sung, chẳng hạn như tệp trên Google Drive, video trên YouTube, Google Biểu mẫu, siêu liên kết URL và tệp đính kèm của tiện ích bổ sung Classroom.
• Bạn có thể giao tất cả mục trong luồng cho một nhóm nhỏ học viên trong khoá học.
• CourseWork có thể được chấm điểm hoặc không được chấm điểm. Giáo viên có thể thay đổi trạng thái chấm điểm của bài tập CourseWork bất cứ lúc nào.
• Một mục trong luồng có thể có nhiều tệp đính kèm.
• Một mục trong luồng có thể có tệp đính kèm thuộc nhiều loại. Ví dụ: một bài tập CourseWork có thể có đồng thời tệp trên Google Drive, video trên YouTube và tệp đính kèm bổ trợ của Lớp học.
• Một mục trong luồng có thể có các tệp đính kèm bổ sung của nhiều nhà phát triển.
• Nhà phát triển có thể nhận và sửa đổi thông tin chi tiết về mọi tài nguyên mục trong bảng tin có một trong các tệp đính kèm tiện ích bổ sung của họ.
• Nhà phát triển có thể nộp, lấy lại hoặc trả lại bài tập đã nộp của học viên cho một bài tập CourseWork có chứa một trong các tệp đính kèm của tiện ích bổ sung.
• Nhà phát triển chỉ có thể hoàn tất việc chấm điểm cho từng bài tập đã nộp của học viên trong các bài tập mà họ đã tạo.

Đã sao chép các mục trong luồng

Giáo viên có thể sao chép một mục trên luồng bằng cách sao chép một khoá học, sử dụng lại bài tập hoặc xuất bản một mục trên luồng cho nhiều khoá học. Mọi bản sao mới sẽ có các giá trị nhận dạng riêng biệt. Đây có thể là một yếu tố quan trọng cần cân nhắc nếu bạn đang phát triển một tiện ích bổ sung cho Lớp học. Hãy đọc hướng dẫn của chúng tôi về nội dung sao chép để hiểu cách một tiện ích bổ sung có thể xử lý những trường hợp này.

CourseWork và StudentSubmissions

Mục CourseWork biểu thị một bài tập cho một nhóm học viên trong một khoá học. Đây là loại mục duy nhất trên bảng tin có thể chấp nhận bài tập mà học viên gửi. Tài nguyên CourseWork chứa các thông tin chi tiết như nội dung mô tả, ngày đến hạn, điểm tối đa và siêu dữ liệu như thời gian tạo.

Mỗi tài nguyên CourseWork mô tả một trong các loại nhiệm vụ sau:

• Một bài tập mà học viên hoàn thành bằng cách nộp phiếu bài tập hoặc các tệp đính kèm khác.
• Câu hỏi 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 cho một mục CourseWork được biểu thị bằng StudentSubmission. Nó 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 và có thể bao gồm:

• Các trang tính và tệp đính kèm được gửi cho bài tập, bao gồm cả tiêu đề, hình thu nhỏ và URL, cũng như các giá trị nhận dạng có thể 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 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 trên lớp và bài làm 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 học tập và thông báo

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. Mỗi tài nguyên đều có thông tin chi tiết như tiêu đề và nội dung mô tả cùng với tài liệu bổ sung. 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ỳ dữ liệu nào. Do đó, không có ngày đến hạn và StudentSubmissions không tồn tại đối với CourseWorkMaterials. Giáo viên có thể sử dụng biểu tượ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ể sắp xếp theo Topics như CourseWork hoặc CourseWorkMaterials. Giáo viên có thể dùng những thông báo này để 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 danh mục này để nhóm 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 và phần phụ trợ do nhà phát triển cung cấp, thường xuất hiện 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 trong luồng phát có thể là Announcements, CourseWork hoặc CourseWorkMaterials. Tệp đính kèm tiện ích bổ sung được biểu thị bằng biểu tượ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 hoạt động yêu cầu học viên hoàn thành và nộp bài tập riêng lẻ. Ví dụ: câu đố, bản vẽ hoặc trò chơi. Bạn có thể tuỳ chọn chấm điểm cho một bài tập.
• Tệp đính kèm nội dung không yêu cầu học viên nộp bài. Học viên không cần nộp tệp đính kèm và tệp này không được chấm điểm. Ví dụ: ảnh, bài viết và video.

Hãy 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 thay đổi trong Google Lớp học. Ví dụ: khi danh sách học viên của một khoá học được cập nhật. Registrations đại diện cho một chỉ dẫn để gửi những 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.