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

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

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

כדי ליצור קובץ מצורף, שולחים בקשת CREATE לנקודת הקצה המתאימה ב-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 כדי לאחזר או לשנות מידע לגבי תוכן שהתלמידים מגישים.

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

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

צריך לשלוח בקשת 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 לא מוגדר או להגדיר אותו כ-0.

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

כדי לשנות את הכתובת שתלמידים מגישים, צריך לשלוח בקשת PATCH לנקודת הקצה של 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 כדי לזהות מתי התלמידים מגישים את העבודה. אחרי שההגשה תבוצע, הגדירו את הציון שלה באמצעות פרטי הכניסה שאוחסנו.

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

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

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

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

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

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

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