หน้านี้จะกล่าวถึงรายละเอียดการใช้งานสำหรับการสร้างไฟล์แนบ การดำเนินการที่แนะนำเมื่อผู้ใช้เปิดไฟล์แนบ และการทำงานกับการส่งงานของนักเรียน โปรดทราบว่าคุณอาจต้องระบุพารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบ เมื่อส่งคำขอเหล่านี้
สร้างไฟล์แนบ
สร้างไฟล์แนบโดยส่งคำขอ CREATE ไปยังปลายทาง courses.*.addOnAttachments.create ที่เหมาะสม คำขอของคุณต้องมีอินสแตนซ์ของ AddOnAttachment ในเนื้อหาคำขอ
คุณต้องระบุข้อมูลในช่องต่อไปนี้เมื่อสร้างไฟล์แนบ
title: ชื่อสตริงของไฟล์แนบteacherViewUri: URI สำหรับมุมมองของครูของไฟล์แนบstudentViewUri: URI สำหรับมุมมองของนักเรียนนักศึกษาของไฟล์แนบstudentWorkReviewUri: URI สำหรับครูเพื่อดูงานของนักเรียนในไฟล์แนบ คุณต้องระบุข้อมูลในช่องนี้สำหรับไฟล์แนบประเภทกิจกรรมเท่านั้น
คุณอาจต้องการระบุข้อมูลในช่องที่ไม่บังคับต่อไปนี้
dueDateและdueTimeหากต้องการระบุเวลาที่ต้องส่งไฟล์แนบmaxPoints: คะแนนสูงสุดสำหรับไฟล์แนบ ต้องเป็นค่าที่ไม่ใช่ 0 หากคุณต้องการรองรับการส่งคะแนนกลับ ใช้ได้กับไฟล์แนบประเภทกิจกรรมเท่านั้น
ดูรายละเอียดเพิ่มเติมเกี่ยวกับช่องเหล่านี้ได้ที่ข้อมูลอ้างอิงทรัพยากร AddOnAttachment
ตรวจสอบข้อมูลเข้าสู่ระบบและบทบาทของผู้ใช้
iframe ของมุมมองของนักเรียน iframe ของการตรวจสอบงานของนักเรียน และมุมมองของครู iframeมีไว้เพื่อแสดงเนื้อหาแก่ผู้ใช้แทนที่จะแก้ไขงานใน Classroom พิจารณาดำเนินการต่อไปนี้เมื่อเปิดมุมมองใดมุมมองหนึ่ง
- รับข้อมูลเข้าสู่ระบบ OAuth สำหรับผู้ใช้
- ส่งคำขอ
courseWork.getAddOnContext,courseWorkMaterials.getAddOnContextหรือannouncements.getAddOnContextตามitemTypeเพื่อตรวจสอบบทบาทของผู้ใช้ - ตรวจสอบการตอบกลับเพื่อดูว่ามี
TeacherContextหรือStudentContextหรือไม่ ระบบจะแสดงผลได้เพียงรายการเดียว ซึ่งสอดคล้องกับบทบาทของผู้ใช้ในหลักสูตร - หากผู้ใช้ปัจจุบันเป็นนักเรียนและ
itemTypeคือcourseWorkให้บันทึกsubmissionIdจากการตอบกลับพร้อมกับงานของนักเรียนsubmissionIdsจะตรงกันใน iframe ของส่วนเสริม และจำเป็นสำหรับการส่งคะแนนกลับและการแสดงงานของนักเรียนให้ครูเห็นในเครื่องมือให้คะแนน - หากส่วนเสริมทราบ
attachmentIdอยู่แล้ว ให้แสดง UI ของไฟล์แนบที่เหมาะสม - หากไม่เป็นเช่นนั้น ไฟล์แนบนี้จะต้องคัดลอกจากรายการสตรีมหรือหลักสูตรอื่น ดูคำแนะนำเกี่ยวกับสถานการณ์นี้ได้ที่คู่มือการจัดการเนื้อหาที่คัดลอกสำหรับ
รายละเอียดการส่งงานของนักเรียน
เวิร์กโฟลว์การส่งงานทั่วไปมีขั้นตอนดังนี้
- นักเรียนเปิด
studentViewUriเพื่อทำกิจกรรมให้เสร็จสมบูรณ์ - ส่วนเสริมจะดึงข้อมูล
submissionIdจากเมธอดgetAddOnContextโดยใช้ข้อมูลเข้าสู่ระบบของนักเรียน - นักพัฒนาส่วนเสริมจะจัดเก็บ
submissionIdและattachmentIdเป็นตัวระบุที่ไม่ซ้ำกันของงานของนักเรียน ในกรณีที่ครูคัดลอกงานใน Classroom คุณสามารถใช้คีย์ผสมของพารามิเตอร์ 2 รายการนี้เพื่อแสดงไฟล์แนบใหม่ในงานที่คัดลอก ดูรายละเอียดเพิ่มเติมได้ที่หน้าเนื้อหาที่คัดลอก - ครูที่สนใจตรวจสอบงานของนักเรียนจะเปิด
studentWorkReviewUriคำขอจะมีพารามิเตอร์การค้นหาต่อไปนี้courseId,itemId,itemType,attachmentIdและsubmissionId - นักพัฒนาส่วนเสริมใช้รหัส 4 รายการนี้เพื่อดึงข้อมูลงานของนักเรียน ใช้
ปลายทาง
courses.courseWork.addOnAttachments.studentSubmissionsเพื่อ ดึงข้อมูลหรือแก้ไขข้อมูลเกี่ยวกับการส่งงานของนักเรียน
ตรวจหาสถานะการส่ง
ส่งคำขอ GET ไปยังปลายทาง
courses.courseWork.addOnAttachments.studentSubmissions เพื่อดูรายละเอียดเกี่ยวกับ submissionId ที่เฉพาะเจาะจง คุณจะได้รับออบเจ็กต์ AddOnAttachmentStudentSubmission ซึ่งมีคะแนนของงานที่ส่ง (pointsEarned) และสถานะปัจจุบัน (postSubmissionState) สถานะการส่งอาจมีค่าใดค่าหนึ่งต่อไปนี้
NEWหากนักเรียนไม่เคยเข้าถึงงานที่ส่งCREATEDหากนักเรียนสร้างงานที่ส่งแล้วแต่ยังไม่ได้ส่งTURNED_INหากนักเรียนส่งงานให้ครูแล้วRETURNEDหากครูส่งงานที่ส่งคืนให้นักเรียนแล้วRECLAIMED_BY_STUDENTหากนักเรียนนักศึกษา "ยกเลิกการส่ง" งาน
ใช้ปลายทางนี้เพื่อตรวจหาสถานะงานของนักเรียนในส่วนเสริม จากนั้นคุณอาจปรับมุมมองหรือตัวเลือกที่แสดงให้นักเรียนตามสถานะที่แสดงผล ซึ่งอาจรวมถึงฟีเจอร์ต่างๆ เช่น
- แสดงสถานะการส่งงานภายในส่วนเสริม ซึ่งอาจช่วยให้นักเรียนหลีกเลี่ยงความสับสนที่อาจเกิดขึ้นและมั่นใจได้ว่าจะไม่ลืมส่งงาน
- จำกัดสิทธิ์ในการแก้ไขงานที่ส่ง หากงานมีสถานะ
CREATEDหรือRECLAIMED_BY_STUDENTนักเรียนอาจได้รับอนุญาตให้แก้ไขงานที่ส่ง หากงานมีสถานะTURNED_INหรือRETURNEDนักเรียนอาจไม่ได้รับอนุญาตให้แก้ไขงานที่ส่ง
คะแนนและไฟล์แนบหลายรายการ
คุณใช้ไฟล์แนบของส่วนเสริมได้เพียงรายการเดียวเพื่อตั้งคะแนนสำหรับงานเดียว หากครูสร้างไฟล์แนบประเภทกิจกรรมมากกว่า 1 รายการซึ่งมีค่า maxPoints เฉพาะไฟล์แนบรายการแรกเท่านั้นที่จะตั้งคะแนนของงานได้ ปล่อยให้ค่า maxPoints ไม่ได้ตั้งค่าหรือตั้งค่าเป็น 0 เพื่อปิดใช้การส่งคะแนนกลับสำหรับไฟล์แนบ
ตั้งคะแนนของงานที่ส่ง
คุณสามารถแก้ไขงานที่นักเรียนส่งโดยส่งคำขอ PATCH ไปยัง
courses.courseWork.addOnAttachments.studentSubmissions ปลายทาง เนื้อหาคำขอต้องมีอินสแตนซ์ของ AddOnAttachmentStudentSubmission ที่มีค่าที่แก้ไขแล้ว ตั้งค่าช่อง pointsEarned เพื่อแก้ไขคะแนนของงานที่ส่ง
ค่าที่ส่งใน pointsEarned จะกลายเป็นคะแนนฉบับร่าง ที่ครูเห็นใน UI ของ Classroom ครูสามารถแก้ไขคะแนนฉบับร่างก่อนที่จะส่งงานคืนให้นักเรียน ดูรายละเอียดเกี่ยวกับวิธีแสดงคะแนนให้ครูเห็นได้ที่ ภาพรวมของการให้คะแนนใน
UI ของ Classroom
โปรดทราบว่าคุณจะตั้งคะแนนด้วย pointsEarned ได้ก็ต่อเมื่อเงื่อนไขต่อไปนี้เป็นจริง
- ไฟล์แนบต้องมีค่า
maxPointsเป็นค่าบวก - ส่วนเสริมต้องเป็นผู้สร้างไฟล์แนบเดิม
โปรดทราบด้วยว่าคุณสามารถแก้ไขค่า maxPoints ของ AddOnAttachment ที่สร้างไว้แล้วได้โดยส่งคำขอ PATCH ไปยังปลายทาง addOnAttachments
เวลาที่ควรตั้งคะแนน
คุณมีตัวเลือกในการส่งคะแนนกลับไปยัง Google Classroom ความแตกต่างที่สำคัญคือคุณเลือกที่จะจัดเก็บข้อมูลเข้าสู่ระบบของครูหรือไม่ เนื่องจากมีเพียงครูเท่านั้นที่แก้ไขคะแนนได้
มีช่วงเวลา 2 ช่วงเวลาที่ส่วนเสริม อาจส่งคะแนนไปยัง Google Classroom ได้ ได้แก่ เมื่อนักเรียนทำงานเสร็จหรือเมื่อครูเปิดงานของนักเรียนใน iframe ของการตรวจสอบงานของนักเรียน
หากต้องการตั้งคะแนนเมื่อนักเรียนทำงานเสร็จ คุณต้องจัดเก็บข้อมูลเข้าสู่ระบบแบบออฟไลน์ของครู จากนั้นดึงข้อมูลเข้าสู่ระบบดังกล่าวมาใช้เพื่อแก้ไขคะแนนเมื่อนักเรียนทำงานเสร็จ วิธีนี้มีข้อดีที่อาจเกิดขึ้นดังนี้
- ให้การอัปเดตคะแนนที่ราบรื่น ครูไม่จำเป็นต้องดำเนินการใดๆ เป็นพิเศษเพื่อให้คะแนนแสดงใน UI ของ Classroom
- ให้ข้อมูลเชิงลึกแบบเรียลไทม์เกี่ยวกับความคืบหน้าของชั้นเรียนในงาน การตั้งคะแนนเมื่อนักเรียนทำไฟล์แนบเสร็จจะช่วยให้ครูทราบความเข้าใจของนักเรียนโดยไม่ต้องเปิดงานที่ส่งทุกรายการ
โปรดทราบว่าแนวทางนี้ยังช่วยให้แนวทางแบบไม่พร้อมกัน ในการซิงค์คะแนนได้ด้วย คุณอาจสำรวจปลายทาง AddOnAttachmentStudentSubmission เป็นระยะๆ เพื่อตรวจหาเวลาที่นักเรียนส่งงาน เมื่อส่งงานแล้ว ให้ตั้งคะแนนของงานที่ส่งโดยใช้ข้อมูลเข้าสู่ระบบที่จัดเก็บไว้
หากไม่ต้องการโหลดข้อมูลเข้าสู่ระบบของครูระหว่างเซสชันของนักเรียน คุณสามารถใช้ข้อมูลเข้าสู่ระบบของครูที่ใช้งานอยู่เมื่อครูโหลดงานที่นักเรียนส่ง ใน iframe ของการตรวจสอบงานของนักเรียน อย่างไรก็ตาม วิธีนี้อาจไม่มอบประสบการณ์การใช้งานที่ราบรื่นนัก เนื่องจากคะแนนใน UI ของ Classroom จะไม่อัปเดตแบบเรียลไทม์ และครูจะต้องเปิด iframe ของการตรวจสอบงานของนักเรียนสำหรับงานที่ส่งทุกรายการ
ตรวจหาการเปลี่ยนแปลงคะแนนของงาน
ครูสามารถแก้ไขการตั้งค่าคะแนนใน Classroom ได้หลังจากสร้างงานแล้ว การแก้ไขดังกล่าวอาจรวมถึง
- การเปลี่ยนคะแนนเต็มที่กำหนด
- การเปลี่ยนค่า
maxPointsของงาน - การเปลี่ยนว่าจะให้คะแนนงานหรือไม่
หากต้องการดูการตั้งค่าการให้คะแนนปัจจุบันของงาน เราขอแนะนำให้คุณส่ง
คำขอ GET ไปยังปลายทาง courses.courseWork การตอบกลับจะมีค่า maxPoints ปัจจุบัน งานที่ไม่ได้ให้คะแนนจะมีค่า maxPoints เป็น Null หรือ 0
หากคุณส่งคะแนนกลับไปยัง Classroom แล้ว ให้ใช้ปลายทาง courses.courseWork.addOnAttachments.studentSubmissions เพื่อดึงหรือเปลี่ยนคะแนนสำหรับไฟล์แนบของส่วนเสริม ระบบจะตั้งค่าคะแนนโดยใช้ช่อง pointsEarned พิจารณาตรวจสอบและอัปเดตค่านี้หากจำเป็น หากผลิตภัณฑ์ของคุณอนุญาตให้ครูแก้ไขคะแนนของนักเรียนสำหรับกิจกรรมที่เฉพาะเจาะจง