Trang này thảo luận về thông tin chi tiết triển khai để tạo tệp đính kèm, các hành động nên thực hiện khi người dùng mở tệp đính kèm và cách xử lý bài tập đã nộp của học viên. Xin lưu ý rằng bạn có thể cần cung cấp các tham số liên quan đến tệp đính kèm khi thực hiện các yêu cầu này.
Tạo tệp đính kèm
Tạo tệp đính kèm bằng cách gửi yêu cầu CREATE đến điểm cuối courses.*.addOnAttachments.create thích hợp. Yêu cầu của bạn phải bao gồm một phiên bản của AddOnAttachment trong nội dung yêu cầu.
Bạn phải điền các trường sau đây khi tạo tệp đính kèm:
title: tên chuỗi của tệp đính kèm.teacherViewUri: URI cho Chế độ xem của giáo viên đối với tệp đính kèm.studentViewUri: URI cho Chế độ xem của học viên đối với tệp đính kèm.studentWorkReviewUri: URI để giáo viên xem bài tập của học viên trong tệp đính kèm. Bạn chỉ phải điền trường này cho tệp đính kèm thuộc loại hoạt động.
Bạn có thể muốn thêm một số trường không bắt buộc sau đây:
dueDatevàdueTimenếu bạn chỉ định thời hạn của tệp đính kèm.maxPoints: điểm tối đa cho tệp đính kèm. Phải là giá trị khác 0 nếu bạn muốn hỗ trợ tính năng chuyển điểm. Chỉ áp dụng cho tệp đính kèm thuộc loại hoạt động.
Hãy xem tài liệu tham khảo về AddOnAttachment tài nguyên để biết thêm thông tin chi tiết về các trường này.
Xác thực thông tin đăng nhập và vai trò của người dùng
iframe Chế độ xem của học viên, iframe Xem bài tập của học viên và iframe Chế độ xem của giáo viên đều nhằm mục đích trình bày nội dung cho người dùng thay vì sửa đổi bài tập trên Classroom. Hãy cân nhắc thực hiện những việc sau khi một trong các khung hiển thị này mở ra:
- Lấy thông tin đăng nhập OAuth cho người dùng.
- Đưa ra yêu cầu
courseWork.getAddOnContext,courseWorkMaterials.getAddOnContexthoặcannouncements.getAddOnContextdựa trênitemTypeđể xác thực vai trò của người dùng. - Kiểm tra phản hồi để xem có
TeacherContexthoặcStudentContexthay không. Chỉ có thể trả về một giá trị, tương ứng với vai trò của người dùng trong khoá học. - Nếu người dùng hiện tại là học viên và
itemTypelàcourseWork, hãy ghi lạisubmissionIdtừ phản hồi cùng với bài tập của học viên.submissionIdskhớp trên các iframe bổ trợ và bắt buộc phải có để chuyển điểm và cho giáo viên xem bài tập của học viên trong công cụ chấm điểm. - Nếu tiện ích bổ sung đã biết
attachmentId, hãy hiện giao diện người dùng tệp đính kèm thích hợp. - Nếu không, tệp đính kèm này phải được sao chép từ một mục khác trong sự kiện phát trực tiếp hoặc khoá học. Hãy xem hướng dẫn Xử lý nội dung sao chép để biết các đề xuất về trường hợp này.
Thông tin chi tiết về bài nộp của học viên
Quy trình gửi điển hình sẽ bao gồm các bước sau:
- Học viên khởi chạy
studentViewUriđể hoàn thành một hoạt động. - Tiện ích bổ sung này truy xuất một
submissionIdtừ phương thứcgetAddOnContextbằng thông tin đăng nhập của học viên. submissionIdvàattachmentIdđược nhà phát triển tiện ích bổ sung lưu trữ dưới dạng giá trị nhận dạng duy nhất của bài tập học viên. Trong trường hợp giáo viên sao chép bài tập trong Lớp học, bạn có thể sử dụng khoá kết hợp của hai tham số này để hiển thị một tệp đính kèm mới trong bài tập đã sao chép. Hãy xem trang của chúng tôi về nội dung sao chép để biết thêm thông tin chi tiết.- Giáo viên muốn xem xét bài tập của học viên sẽ khởi chạy
studentWorkReviewUri. Yêu cầu này bao gồm các tham số truy vấn sau:courseId,itemId,itemType,attachmentIdvàsubmissionId. - Nhà phát triển tiện ích bổ sung sử dụng 4 mã nhận dạng này để truy xuất bài tập của học viên. Sử dụng điểm cuối
courses.courseWork.addOnAttachments.studentSubmissionsđể truy xuất hoặc sửa đổi thông tin về bài tập mà học viên đã nộp.
Phát hiện trạng thái gửi
Gửi yêu cầu GET đến điểm cuối courses.courseWork.addOnAttachments.studentSubmissions để biết thông tin chi tiết về một submissionId cụ thể. Bạn sẽ nhận được một đối tượng AddOnAttachmentStudentSubmission, trong đó có điểm (pointsEarned) và trạng thái hiện tại (postSubmissionState) của bài tập đã gửi. Trạng thái của bài tập đã gửi có thể là một trong các giá trị sau:
NEW, nếu học viên chưa từng truy cập vào bài tập đã gửi.CREATED, nếu học viên đã tạo bài tập nhưng chưa gửi.TURNED_IN, nếu học viên đã gửi bài tập cho giáo viên.RETURNED, nếu giáo viên đã trả bài cho học viên.RECLAIMED_BY_STUDENT, nếu học viên "chưa gửi" bài tập.
Sử dụng điểm cuối này để phát hiện trạng thái bài tập của học viên trong tiện ích bổ sung. Sau đó, bạn có thể điều chỉnh các chế độ xem hoặc lựa chọn được cung cấp cho học viên tuỳ thuộc vào trạng thái được trả về. Điều này có thể bao gồm những tính năng như:
- Hiển thị trạng thái nộp bài của bài tập trong tiện ích bổ sung. Điều này có thể giúp học viên tránh nhầm lẫn và đảm bảo họ không vô tình không nộp bài tập.
- Hạn chế quyền chỉnh sửa bản gửi. Nếu bài tập có trạng thái
CREATEDhoặcRECLAIMED_BY_STUDENT, thì học viên có thể được phép chỉnh sửa bài tập đã nộp. Nếu bài tập có trạng tháiTURNED_INhoặcRETURNED, thì học viên có thể không được phép chỉnh sửa bài tập đã nộp.
Điểm và nhiều tệp đính kèm
Bạn chỉ có thể dùng một tệp đính kèm tiện ích bổ sung để đặt điểm cho một bài tập. Nếu giáo viên tạo nhiều tệp đính kèm thuộc loại hoạt động cung cấp giá trị maxPoints, thì chỉ tệp đính kèm đầu tiên như vậy mới có thể đặt điểm số của bài tập. Bạn có thể để trống giá trị maxPoints hoặc đặt giá trị này thành 0 để tắt tính năng chuyển điểm trở lại cho tệp đính kèm.
Đặt điểm cho bài nộp
Bạn có thể sửa đổi bài tập đã nộp của học viên bằng cách gửi yêu cầu PATCH đến điểm cuối courses.courseWork.addOnAttachments.studentSubmissions. Nội dung yêu cầu phải bao gồm một phiên bản của AddOnAttachmentStudentSubmission có các giá trị đã sửa đổi. Đặt trường pointsEarned để sửa đổi điểm của bài tập đã gửi.
Giá trị được truyền trong pointsEarned sẽ trở thành điểm nháp mà giáo viên có thể thấy trong giao diện người dùng Lớp học. Giáo viên có thể sửa đổi điểm không chính thức trước khi trả bài tập cho học viên. Hãy xem bài viết Tổng quan về việc chấm điểm trong giao diện người dùng Lớp học để biết thông tin chi tiết về cách điểm được trình bày cho giáo viên.
Xin lưu ý rằng bạn chỉ có thể đặt điểm bằng pointsEarned nếu những điều kiện sau đây là đúng:
- Tệp đính kèm phải có giá trị
maxPointsdương. - Tiện ích bổ sung phải là nhà sáng tạo ban đầu của tệp đính kèm.
Xin lưu ý rằng bạn cũng có thể sửa đổi giá trị maxPoints của AddOnAttachment đã tạo bằng cách gửi yêu cầu PATCH đến điểm cuối addOnAttachments.
Thời điểm đặt điểm
Bạn có thể chọn thời điểm trả lại điểm cho Google Lớp học. Điểm khác biệt quan trọng là việc bạn có chọn lưu trữ thông tin đăng nhập của giáo viên hay không, vì chỉ giáo viên mới có thể sửa đổi điểm.
Có hai thời điểm bổ sung mà bạn có thể chuyển điểm cho Google Lớp học: khi học viên hoàn thành bài tập hoặc khi giáo viên mở bài tập của học viên trong iframe Đánh giá bài tập của học viên.
Nếu muốn đặt điểm khi học viên hoàn thành bài tập, bạn phải lưu trữ thông tin đăng nhập ngoại tuyến của giáo viên, sau đó truy xuất và sử dụng thông tin đăng nhập đó để sửa đổi điểm khi học viên hoàn thành bài tập. Phương pháp này mang lại một số lợi ích tiềm năng:
- Cung cấp thông tin cập nhật điểm liền mạch. Giáo viên không cần thực hiện bất kỳ thao tác đặc biệt nào để điểm xuất hiện trong giao diện người dùng Lớp học.
- Cung cấp thông tin chi tiết theo thời gian thực về tiến trình của một lớp học trong quá trình làm bài tập. Bằng cách đặt điểm khi học viên hoàn thành tệp đính kèm, giáo viên có thể nắm được mức độ hiểu bài của học viên mà không cần mở từng bài nộp.
Xin lưu ý rằng phương pháp này cũng cho phép phương pháp không đồng bộ để đồng bộ hoá điểm. Bạn có thể định kỳ thăm dò điểm cuối AddOnAttachmentStudentSubmission để phát hiện thời điểm học viên đã nộp bài tập. Khi bài tập đã được gửi, hãy đặt điểm cho bài tập đó bằng thông tin xác thực đã lưu trữ.
Nếu không muốn tải thông tin đăng nhập của giáo viên trong phiên hoạt động của học viên, bạn có thể sử dụng thông tin đăng nhập của giáo viên đang hoạt động khi họ tải bài tập đã nộp của học viên trong iframe Đánh giá bài tập của học viên. Tuy nhiên, cách này có thể không mang lại trải nghiệm người dùng đặc biệt mượt mà vì điểm số trong giao diện người dùng Lớp học không cập nhật theo thời gian thực và giáo viên sẽ phải mở iframe Đánh giá bài tập của học viên cho từng bài tập đã nộp.
Phát hiện thay đổi về điểm số của bài tập
giáo viên có thể chỉnh sửa chế độ cài đặt điểm trong Lớp học sau khi tạo bài tập. Những nội dung chỉnh sửa đó có thể bao gồm:
- Thay đổi giá trị điểm được giao.
- Thay đổi giá trị
maxPointscủa bài tập. - Thay đổi việc có chấm điểm bài tập hay không.
Để xem chế độ cài đặt chấm điểm hiện tại của một bài tập, bạn nên gửi một yêu cầu GET đến điểm cuối courses.courseWork. Phản hồi bao gồm giá trị maxPoints hiện tại. Bài tập chưa chấm điểm có giá trị maxPoints bằng 0 hoặc rỗng.
Nếu bạn đã chuyển điểm về Lớp học, hãy sử dụng điểm cuối courses.courseWork.addOnAttachments.studentSubmissions để tìm nạp hoặc thay đổi điểm cho tệp đính kèm tiện ích bổ sung. Giá trị điểm được đặt bằng trường pointsEarned. Hãy cân nhắc kiểm tra và cập nhật giá trị này (nếu cần) nếu sản phẩm của bạn cho phép giáo viên chỉnh sửa điểm số của học viên cho một hoạt động cụ thể.