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

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

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

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

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

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

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

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

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

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

תהליך השליחה הרגיל כולל את השלבים הבאים:

1. תלמיד/ה מפעיל/ה את studentViewUri כדי להשלים פעילות.
2. התוסף מאחזר submissionId מהשיטה getAddOnContext באמצעות פרטי הכניסה של התלמידים.
3. המפתחות submissionId ו-attachmentId נשמרים על ידי מפתח התוסף בתור המזהה הייחודי של העבודה של התלמיד/ה. אם מורה מעתיק מטלה ב-Classroom, אפשר להשתמש במפתח המשולב של שני הפרמטרים האלה כדי להציג קובץ מצורף חדש במטלה המועתקת. לפרטים נוספים, אפשר לעיין בדף שלנו בנושא תוכן שהועתק.
4. מורים שרוצים לבדוק עבודות של תלמידים פותחים את האפשרות studentWorkReviewUri. הבקשה כוללת את פרמטרי השאילתה הבאים: courseId, itemId, itemType, attachmentId ו-submissionId.
5. מפתח התוסף משתמש בארבעת המזהים האלה כדי לאחזר את העבודות של התלמידים. אפשר להשתמש בנקודת הקצה 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, יכול להיות שהתלמיד לא יוכל לערוך את המטלה שהגיש.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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