Tương tác với tệp đính kèm

Trang này thảo luận chi tiết cách triển khai của việc tạo tệp đính kèm và cách xử lý bài làm mà học viên nộp. 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 đưa ra 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 bản sao 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 dành cho giáo viên của tệp đính kèm.
studentViewUri: URI cho tệp đính kèm mà học viên xem.
studentWorkReviewUri: URI để giáo viên xem bài tập của học viên trên tệp đính kèm. Trường này chỉ bắt buộc đối với các tệp đính kèm loại hoạt động.

Bạn có thể muốn bao gồm một số trường không bắt buộc sau:

dueDate và dueTime nếu chỉ định thời điểm đến hạn của tệp đính kèm.
maxPoints: điểm tối đa cho tệp đính kèm. Phải là một giá trị khác 0 nếu bạn muốn hỗ trợ tính năng trả điểm về. Chỉ áp dụng cho các tệp đính kèm loại hoạt động.

Hãy xem tài liệu tham khảo về AddOnAttachment để biết thêm thông tin về các trường này.

Thông tin chi tiết về bài học viên nộp

Quy trình gửi thông thường tuân theo các bước sau:

Một học viên chạy studentViewUri để hoàn tất một hoạt động.
Tiện ích bổ sung này truy xuất submissionId từ phương thức getAddOnContext bằng thông tin đăng nhập của học viên.
Tiện ích bổ sung sẽ lưu trữ submissionId và attachmentId dưới dạng giá trị nhận dạng duy nhất đối với bài tập của học viên. Trong trường hợp giáo viên sao chép một bài tập trong Lớp học, bạn có thể sử dụng khoá tổng hợp của 2 tham số này để cho thấy 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 được sao chép để biết thêm chi tiết.
Một giáo viên muốn đánh giá bài tập của học viên sẽ phát hành studentWorkReviewUri. Yêu cầu này bao gồm các tham số truy vấn sau: courseId, itemId, itemType, attachmentId và 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 gửi.

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 để nhận thông tin chi tiết về một submissionId cụ thể. Bạn sẽ nhận được một đối tượng AddOnAttachmentStudentSubmission, chứa điểm (pointsEarned) và trạng thái hiện tại của bài gửi (postSubmissionState). Trạng thái gửi có thể là một trong những giá trị sau:

NEW, nếu học viên chưa từng truy cập vào bài tập.
CREATED, nếu học viên đã tạo bài nộp nhưng chưa nộp.
TURNED_IN, nếu học viên đã nộp bài tập của mình cho giáo viên.
RETURNED, nếu giáo viên đã trả lại bài tập cho học viên.
RECLAIMED_BY_STUDENT, nếu học viên đã "huỷ nộp" bài tập.

Hãy 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 thành phần hiển thị hoặc các tuỳ chọn được cung cấp cho học viên, tuỳ thuộc vào trạng thái trả về. Điều này có thể bao gồm các 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 của bạn. Việc này có thể giúp học viên tránh nguy cơ nhầm lẫn và đảm bảo rằng họ không nộp nhầm bài tập.
Hạn chế đặc quyền chỉnh sửa gửi. Nếu bài tập có trạng thái CREATED hoặc RECLAIMED_BY_STUDENT, 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ái TURNED_IN hoặc RETURNED, 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ể sử dụng một tệp đính kèm bằng 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 đó mới có thể đặt điểm bài tập. Hãy không đặt giá trị maxPoints hoặc đặt giá trị đó thành 0 để tắt tính năng trả điểm cho tệp đính kèm.

Đặt điểm cho bài tập

Bạn có thể sửa đổi bài tập mà học viên nộp 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 thực thể của AddOnAttachmentStudentSubmission với các giá trị được sửa đổi. Đặt trường pointsEarned để sửa đổi điểm của bài nộp. Giá trị được truyền vào pointsEarned sẽ trở thành điểm không chính thức mà giáo viên có thể nhìn thấy trong giao diện người dùng của 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. Xem bài viết Tổng quan về cách 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 giáo viên hiển thị điểm.

Xin lưu ý rằng bạn chỉ có thể đặt điểm bằng pointsEarned nếu những điều sau đây là đúng:

Tệp đính kèm phải có giá trị maxPoints dương.
Tiện ích bổ sung này phải là tác giả ban đầu của tệp đính kèm.

Ngoài ra, xin lưu ý rằng bạn 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ó một số lựa chọn về thời điểm trả điểm về Google Lớp học. Điểm khác biệt quan trọng là bạn có chọn lưu trữ thông tin đăng nhập của giáo viên, vì chỉ giáo viên mới có thể sửa đổi điểm.

Có hai khoảnh khắc bổ sung mà bạn có thể chuyển điểm sang 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 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 xác thực ngoại tuyến của giáo viên, sau đó truy xuất và sử dụng thông tin đó để sửa đổi điểm khi học viên hoàn thành bài tập. Phương thức này mang lại một số lợi ích tiềm năng:

Cập nhật điểm một cách liền mạch. Giáo viên không cần thực hiện bất kỳ hành động đặc biệt nào để đưa điểm vào 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 độ của một lớp học thông qua một bài tập. Bằng cách đặt điểm dưới dạng 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.

Lưu ý rằng phương pháp này cũng cho phép phương pháp không đồng bộ để chấm điểm đồng bộ hoá. 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. Sau khi nộp bài, hãy đặt điểm của bài nộp bằng cách sử dụng thông tin đăng nhập đã lưu trữ.

Nếu không muốn tải thông tin đăng nhập của giáo viên trong một buổi học 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 mà học viên đã nộp trong iframe 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 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 Bài tập của học viên trong mọi bài gửi.

Phát hiện các thay đổi về điểm 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. Các nội dung chỉnh sửa đó có thể bao gồm:

Thay đổi giá trị điểm được chỉ định.
Thay đổi giá trị maxPoints của một bài tập.
Thay đổi việc có nên 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 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. Một bài tập chưa chấm điểm có giá trị maxPoints rỗng hoặc bằng 0.

Nếu bạn đã trả điểm vào Lớp học, hãy sử dụng điểm cuối courses.courseWork.addOnAttachments.studentSubmissions để tìm nạp hoặc đổi điểm cho một tệp đính kèm của tiện ích bổ sung. Giá trị điểm được đặt bằng trường pointsEarned. 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 của học viên cho một hoạt động cụ thể.