โต้ตอบกับไฟล์แนบ

หน้านี้จะอธิบายรายละเอียดการติดตั้งใช้งานสำหรับการสร้างไฟล์แนบ การดำเนินการที่แนะนำเมื่อผู้ใช้เปิดไฟล์แนบ และการทำงานกับ งานที่นักเรียน/นักศึกษาส่ง โปรดทราบว่าคุณอาจต้องระบุพารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบ เมื่อส่งคำขอเหล่านี้

สร้างไฟล์แนบ

สร้างไฟล์แนบโดยส่งคำขอ 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 ของไฟล์แนบที่เหมาะสม
• ไม่เช่นนั้น ไฟล์แนบนี้ต้องคัดลอกมาจากรายการสตรีมหรือ หลักสูตรอื่น ดูคำแนะนำเกี่ยวกับสถานการณ์นี้ในคู่มือการจัดการเนื้อหาที่คัดลอกมา

รายละเอียดงานที่นักเรียนส่ง

โดยทั่วไปเวิร์กโฟลว์การส่งจะทำตามขั้นตอนต่อไปนี้

1. นักเรียน/นักศึกษาเปิด studentViewUri เพื่อทำกิจกรรมให้เสร็จ
2. ส่วนเสริมจะเรียก submissionId จากเมธอด getAddOnContext โดยใช้ข้อมูลเข้าสู่ระบบของนักเรียน
3. ส่วนเสริมจะจัดเก็บ submissionId และ attachmentId ไว้เป็นตัวระบุที่ไม่ซ้ำกันของงานของนักเรียน ในกรณีที่ครูคัดลอกงานใน Classroom คุณสามารถใช้คีย์แบบรวมของพารามิเตอร์ 2 รายการนี้เพื่อแสดงไฟล์แนบใหม่ในงานที่คัดลอกได้ ดูรายละเอียดเพิ่มเติมได้ที่หน้าเนื้อหาที่คัดลอก
4. ครูที่สนใจตรวจงานของนักเรียนจะเปิดstudentWorkReviewUri คำขอมีพารามิเตอร์การค้นหาต่อไปนี้ courseId, itemId, itemType, attachmentId และ submissionId
5. นักพัฒนาส่วนเสริมใช้รหัสทั้ง 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 รายการเพื่อตั้งคะแนนสำหรับ งานเดียว หากครูสร้างไฟล์แนบประเภทกิจกรรมมากกว่า 1 รายการที่มีmaxPoints ค่า เฉพาะไฟล์แนบรายการแรกเท่านั้นที่ตั้งค่าคะแนนของงานได้ ปล่อยให้ค่า maxPoints ไม่ได้ตั้งค่าหรือตั้งค่าเป็น 0 เพื่อ ปิดใช้การส่งคะแนนกลับสำหรับไฟล์แนบ

ให้คะแนนงาน

คุณแก้ไขงานที่นักเรียน/นักศึกษาส่งได้โดยส่งPATCHคำขอไปยังปลายทาง courses.courseWork.addOnAttachments.studentSubmissions เนื้อความของคำขอ ต้องมีอินสแตนซ์ของ AddOnAttachmentStudentSubmission ที่มีค่าที่ แก้ไขแล้ว ตั้งค่าฟิลด์ pointsEarned เพื่อแก้ไขคะแนนของงาน ค่าที่ส่งใน pointsEarned จะกลายเป็นคะแนนฉบับร่างที่ครูมองเห็นได้ใน UI ของ Classroom ครูสามารถแก้ไขคะแนนฉบับร่าง ก่อนส่งคืนงานให้นักเรียนได้ ดูรายละเอียดเกี่ยวกับวิธีแสดงคะแนนต่อครูได้ที่ภาพรวมของการให้คะแนนใน UI ของ Classroom

โปรดทราบว่าคุณจะตั้งค่าเกรดด้วย pointsEarned ได้ก็ต่อเมื่อเงื่อนไขต่อไปนี้เป็นจริง

• ไฟล์แนบต้องมีค่า maxPoints เป็นบวก
• ส่วนเสริมต้องเป็นผู้สร้างไฟล์แนบเดิม

นอกจากนี้ โปรดทราบว่าคุณสามารถแก้ไขAddOnAttachmentmaxPoints ค่าที่สร้างไว้แล้วได้โดยส่งคำขอ PATCH ไปยังปลายทาง addOnAttachments

เมื่อใดที่ควรให้คะแนน

คุณมีตัวเลือกในการกำหนดเวลาส่งคืนคะแนนไปยัง Google Classroom ความแตกต่างที่สำคัญคือคุณเลือกที่จะจัดเก็บข้อมูลเข้าสู่ระบบของครูหรือไม่ เนื่องจาก มีเพียงครูเท่านั้นที่แก้ไขคะแนนได้

มี 2 ช่วงเวลาที่ส่วนเสริมจะทำงานซึ่งคุณอาจส่งคะแนนไปยัง Google Classroom ได้ ได้แก่ เมื่อนักเรียนทำงานเสร็จ หรือเมื่อครู เปิดงานของนักเรียนใน iframe ของการตรวจงานของนักเรียน

หากต้องการตั้งคะแนนเมื่อนักเรียนทำงานเสร็จ คุณต้องจัดเก็บ ข้อมูลเข้าสู่ระบบแบบออฟไลน์ของครู จากนั้นเรียกข้อมูลและใช้เพื่อแก้ไขคะแนน เมื่อนักเรียนทำงานเสร็จ วิธีนี้มีประโยชน์บางประการที่อาจเกิดขึ้น ดังนี้

• อัปเดตคะแนนได้อย่างราบรื่น ครูไม่จำเป็นต้องดำเนินการใดๆ เป็นพิเศษ เพื่อให้คะแนนปรากฏใน UI ของ Classroom
• ให้ข้อมูลเชิงลึกแบบเรียลไทม์เกี่ยวกับความคืบหน้าของชั้นเรียนในการทำงานที่ได้รับมอบหมาย การตั้งค่าคะแนนเมื่อนักเรียนทำไฟล์แนบเสร็จจะช่วยให้ครูทราบ ระดับความเข้าใจของนักเรียนโดยไม่ต้องเปิดงานที่ส่งมาทุกชิ้น

โปรดทราบว่าวิธีนี้ยังช่วยให้การซิงค์คะแนนเป็นแบบไม่พร้อมกันได้ด้วย คุณอาจสำรวจAddOnAttachmentStudentSubmission ปลายทางเป็นระยะๆ เพื่อตรวจหาเวลาที่นักเรียนส่งงาน เมื่อส่งแล้ว ให้ตั้งค่าคะแนนของงานที่ส่งโดยใช้ข้อมูลเข้าสู่ระบบที่จัดเก็บไว้

หากไม่ต้องการโหลดข้อมูลเข้าสู่ระบบของครูในระหว่างเซสชันของนักเรียน คุณสามารถใช้ข้อมูลเข้าสู่ระบบของครูที่ใช้งานอยู่เมื่อครูโหลดงานที่นักเรียนส่ง ใน iframe การตรวจงานของนักเรียน อย่างไรก็ตาม วิธีนี้อาจไม่มอบประสบการณ์การใช้งานที่ราบรื่นเป็นพิเศษ เนื่องจากคะแนนใน UI ของ Classroom จะไม่อัปเดตแบบเรียลไทม์ และครูจะต้องเปิด iframe การตรวจงานของนักเรียน ของงานที่ส่งทุกรายการ

ตรวจหาการเปลี่ยนแปลงในคะแนนงาน

ครูสามารถแก้ไขการตั้งค่าคะแนนใน Classroom ได้หลังจากสร้างงานแล้ว การแก้ไขดังกล่าวอาจรวมถึงสิ่งต่อไปนี้

• การเปลี่ยนคะแนนเต็มที่กำหนดไว้
• การเปลี่ยนค่า maxPoints ของงาน
• การเปลี่ยนว่าควรให้คะแนนงานหรือไม่

หากต้องการดูการตั้งค่าการให้คะแนนปัจจุบันของงาน เราขอแนะนำให้คุณส่ง GETคำขอไปยังปลายทาง courses.courseWork การตอบกลับประกอบด้วยmaxPointsค่าปัจจุบัน งานที่ไม่มีคะแนนจะมีค่าเป็น Null หรือ 0 maxPoints

หากส่งคะแนนกลับไปยัง Classroom แล้ว ให้ใช้courses.courseWork.addOnAttachments.studentSubmissionsปลายทางเพื่อดึงข้อมูลหรือ แก้ไขคะแนนสำหรับไฟล์แนบของส่วนเสริม คุณตั้งค่าเกรดได้โดยใช้ฟิลด์ pointsEarned โปรดตรวจสอบและอัปเดตค่านี้ (หากจำเป็น) หากผลิตภัณฑ์ของคุณอนุญาตให้ครูแก้ไขคะแนนของนักเรียนสำหรับกิจกรรมหนึ่งๆ