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

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

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

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

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

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

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

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

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

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

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

  1. תלמיד/ה מפעיל/ה את studentViewUri כדי להשלים פעילות.
  2. התוסף מאחזר submissionId מה-method 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 לנקודת הקצה (endpoint) 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. אם המוצר שלכם מאפשר למורים לערוך את הציון של תלמיד או תלמידה בפעילות מסוימת, מומלץ לבדוק את הערך הזה ולעדכן אותו לפי הצורך.