אינטראקציה עם קבצים מצורפים

בדף הזה מתוארים פרטי ההטמעה ליצירת קובץ מצורף לעבוד עם הגשות של תלמידים. לתשומת ליבכם: ייתכן שיהיה צורך לספק פרמטרים שקשורים לקובץ מצורף כששולחים את הבקשות האלה.

יצירת קובץ מצורף

כדי ליצור קובץ מצורף, יש לשלוח בקשת CREATE אל נקודת הקצה courses.*.addOnAttachments.create. הבקשה שלך חייבת לכלול מופע של AddOnAttachment בגוף הבקשה.

כשיוצרים קובץ מצורף, צריך למלא את השדות הבאים:

• title: שם המחרוזת של הקובץ המצורף.
• teacherViewUri: ה-URI לתצוגה למורים של הקובץ המצורף.
• studentViewUri: ה-URI לתצוגת התלמידים של הקובץ המצורף.
• studentWorkReviewUri: ה-URI שמאפשר למורה לראות את העבודות של התלמיד/ה את הקובץ המצורף. השדה הזה נדרש רק לקבצים מצורפים מסוג פעילות.

כדאי לכלול כמה מהשדות האופציונליים הבאים:

• dueDate ו-dueTime אם מציינים את מועד ההגשה של הקובץ המצורף.
• maxPoints: הציון המקסימלי לקובץ המצורף. חייב להיות ערך שאינו אפס אם רוצים לתמוך בציון passback. חלה על קבצים מצורפים מסוג פעילות בלבד.

אפשר למצוא פרטים נוספים על השדות האלה במשאבי העזרה AddOnAttachment.

פרטי ההגשה של התלמיד/ה

תהליך עבודה אופייני של שליחת בקשות כולל את השלבים הבאים:

1. תלמיד או תלמידה מפעילים את studentViewUri כדי להשלים פעילות.
2. התוסף מאחזר submissionId מה-method getAddOnContext באמצעות פרטי הכניסה של התלמידים.
3. הקבצים submissionId ו-attachmentId שמורים בתוסף בתור המזהה הייחודי של העבודה של התלמיד. במקרה שבו כשמורים מעתיקים מטלה ב-Classroom, אפשר להשתמש המפתח המורכב של שני הפרמטרים האלה כדי להציג קובץ מצורף חדש שהוא הועתק. אפשר לקרוא פרטים נוספים בדף שלנו בנושא תוכן מועתק.
4. מורה שמעוניין לעיין בעבודות של תלמידים משיק את studentWorkReviewUri הבקשה כוללת את הפרמטרים הבאים של שאילתה: courseId, itemId, itemType, attachmentId וגם submissionId.
5. מפתח התוסף משתמש בארבעת המזהים האלה כדי לאחזר את העבודות של התלמידים. כדאי להשתמש נקודת הקצה courses.courseWork.addOnAttachments.studentSubmissions לאחזר או לשנות מידע על הגשה של תלמיד.

חשוב: כששולחים בקשות PATCH, חשוב לספק גם את updateMask. הערך updateMask צריך להיות רשימה מופרדת בפסיקים של הפרמטרים שמות של שדות שמשנים.

זיהוי מצב השליחה

יש לשלוח בקשת GET אל נקודת קצה (endpoint) courses.courseWork.addOnAttachments.studentSubmissions לקבלת פרטים על submissionId ספציפי. מקבלים אובייקט AddOnAttachmentStudentSubmission, שמכיל את הציון של המטלה (pointsEarned) והמצב הנוכחי (postSubmissionState). מצב השליחה יכול להיות אחד מהערכים הבאים:

• NEW, אם התלמיד/ה מעולם לא ניגש/ה להגשה.
• CREATED, אם התלמיד/ה יצר/ה מטלה אבל עדיין לא הגיש אותה.
• TURNED_IN, אם התלמיד/ה הגיש/ה את העבודה למורה.
• RETURNED, אם המורה החזיר/ה את המטלה לתלמיד/ה.
• RECLAIMED_BY_STUDENT, אם התלמיד/ה 'לא הוגשה' את עבודתם.

אפשר להשתמש בנקודת הקצה הזו כדי לזהות את מצב העבודות של התלמיד/ה בתוסף. שלך ואז לשנות את התצוגות או האפשרויות שהתלמיד מקבל בהתאם הוחזרה. התכונות האלה עשויות לכלול, למשל:

• הצגת סטטוס ההגשה של מטלות בתוסף. עשויה לעזור לתלמידים להימנע מבלבול אפשרי ולוודא שהם לא טועים לא ניתן להגיש מטלה.
• הגבלת הרשאות עריכה בהגשה. אם למטלה יש סטטוס CREATED או RECLAIMED_BY_STUDENT, יכול להיות שהתלמיד או התלמידה יוכלו לערוך שהם מגישים. אם הסטטוס של המטלה הוא TURNED_IN או RETURNED, ייתכן שהתלמידים לא יוכלו לערוך את המטלה שהם הגישו.

ציונים וקבצים מצורפים מרובים

נקודה חשובה: כדאי לאפשר למורים להפעיל או להשבית ציונים passback כשיוצרים קובץ מצורף.

ניתן להשתמש בקובץ מצורף אחד בלבד של תוסף כדי לקבוע את הציון עבור פריט בודד הקצאה. אם מורה יוצר יותר מקובץ מצורף אחד של סוג פעילות, מספק ערך maxPoints, רק הקובץ המצורף הראשון יכול להגדיר בציון מטלות. צריך להשאיר את הערך של maxPoints לא מוגדר או להגדיר אותו כ-0 להשבית את מתן הציון לקובץ מצורף.

הגדרת הציון להגשה

אפשר לשנות בקשה של תלמיד/ה על ידי שליחת בקשת PATCH אל נקודת קצה (endpoint) courses.courseWork.addOnAttachments.studentSubmissions. הבקשה גוף חייב לכלול מופע של AddOnAttachmentStudentSubmission עם ערכים ששונו. כדי לשנות את הציון של המטלה צריך להגדיר את השדה pointsEarned. הערך שמועבר ב-pointsEarned הופך לטיוטה של ציון שגלוי למורה בממשק המשתמש של Classroom. מורים יכולים לשנות את טיוטת הציונים לפני החזרת המטלה לתלמידים. אפשר לעיין בקטע סקירה כללית של מערכת למתן ציונים ממשק המשתמש של Classroom עם הסבר על הציונים שהוצגו למורים.

אזהרה: העדכונים של ציונים בממשק המשתמש של Google Classroom לא מתרחשים בזמן אמת. ייתכן עיכוב של עד 30 שניות מרגע קבלת הציון ועד הוא מוצג ב-Classroom.

הערה: אפשר להגדיר את הציון עם pointsEarned רק אם: נכון:

• בקובץ המצורף צריך להיות ערך maxPoints חיובי.
• התוסף חייב להיות היוצר המקורי של הקובץ המצורף.

לתשומת ליבך גם אפשר לשנות maxPoints של AddOnAttachment שכבר נוצר באמצעות שליחה של בקשת PATCH אל נקודת הקצה של addOnAttachments.

מתי להגדיר ציון

אתם יכולים לבחור מתי הציון יועבר בחזרה ל-Google Classroom. ההבדל המשמעותי ביותר הוא אם תבחרו לשמור את ההסמכות של המורים, רק למורה יש אפשרות לשנות ציון.

יש שני רגעים של הוספה שבהם אפשר להעביר ציון Google Classroom: כשהתלמידים מסיימים את העבודה או כשהמורה פותח את העבודה של התלמיד/ה ב-iframe של הביקורת על עבודות התלמידים.

אם אתם רוצים להגדיר ציונים כשהתלמידים מסיימים את העבודה, אתם צריכים לשמור את פרטי הכניסה של המורה ללא חיבור לאינטרנט, ואז לאחזר ולהשתמש בהם כדי לשנות את הציון כשהתלמיד משלים את העבודה. השיטה הזאת מספקת יתרונות:

• לספק עדכוני ציונים בצורה חלקה. המורים לא צריכים לבצע פעולות מיוחדות כדי לגרום לאכלוס של ציונים בממשק המשתמש של Classroom.
• לספק תובנות בזמן אמת לגבי התקדמות הכיתה במטלה. כשמגדירים ציונים כשתלמידים משלימים קבצים מצורפים, המורים יכולים להבין של התלמידים להבנה מבלי לפתוח כל הגשה.

שימו לב שהגישה הזו מאפשרת גם לגישה אסינכרונית לתת ציון לסנכרן אפשר לערוך מדי פעם סקר בAddOnAttachmentStudentSubmission נקודת קצה (endpoint) לזיהוי מתי התלמיד או התלמידה הגישו את העבודה שלהם. אחרי שהיה נשלח, יש להגדיר את הציון של המטלה באמצעות פרטי הכניסה שאוחסנו.

אם אתם לא רוצים לטעון את פרטי הכניסה של המורה במהלך סשן של תלמידים, אפשר להשתמש בפרטי הכניסה של המורה הפעיל/ה כשהוא טוענת את החשבון של התלמיד/ה במסגרות של סקירת עבודות התלמידים. עם זאת, הדבר לא יכול לספק לספק חוויית משתמש חלקה במיוחד כציונים בממשק המשתמש של Classroom. לא מעדכנים בזמן אמת, והמורים יידרשו לפתוח iframe של הביקורת על עבודות התלמידים בהגשה.

זיהוי שינויים בציונים של מטלות

נקודה חשובה: כדאי לבדוק את ההגדרות הנוכחיות של מתן ציונים למטלה לפני וקביעת ציון להגשה.

מורים יכולים לערוך את הגדרות הציונים ב-Classroom אחרי יצירת מטלה. עריכות כאלה עשויות כוללים:

• שינוי של ערך הנקודות שהוקצה.
• שינוי הערך maxPoints של מטלה.
• שינוי אם צריך לתת ציון למטלה.

כדי לראות את ההגדרות הנוכחיות למתן ציונים של מטלה, מומלץ לשלוח בקשת GET לנקודת הקצה (endpoint) courses.courseWork. התגובה כוללת בערך הנוכחי של maxPoints. במטלה ללא ציון יש ערך null או אפס. ערך של maxPoints.

אם העברתם ציון בחזרה ל-Classroom, צריך להשתמש נקודת קצה אחת (courses.courseWork.addOnAttachments.studentSubmissions) לאחזור או לשנות את הציון של קובץ מצורף של תוסף. ערך הציון נקבע באמצעות הפונקציה שדה pointsEarned. מומלץ לבדוק את הערך, ואם יש צורך לעדכן אותו, אם המוצר מאפשר למורים לערוך את הציון של תלמיד מסוים פעילות.