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

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

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

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

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

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

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

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

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

אימות של פרטי הכניסה והתפקיד של המשתמש

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

• מקבלים פרטי כניסה של OAuth עבור המשתמש.
• שולחים בקשת courseWork.getAddOnContext,‏ courseWorkMaterials.getAddOnContext או announcements.getAddOnContext בהתאם ל-itemType כדי לאמת את תפקיד המשתמש.
• בודקים את התשובה כדי לראות אם יש בה TeacherContext או StudentContext. אפשר להחזיר רק אחד, בהתאם לתפקיד המשתמש בקורס.
• אם המשתמש הנוכחי הוא תלמיד/ה והערך של itemType הוא courseWork, מתעדים את submissionId מהתגובה עם העבודה של התלמיד/ה. הערך של submissionIds צריך להיות זהה ב-iframe של התוסף, והוא נדרש כדי להחזיר ציונים ולהציג למורים את עבודות התלמידים בכלי למתן ציונים.
• אם התוסף כבר מכיר את attachmentId, מוצג ממשק המשתמש המתאים של הקובץ המצורף.
• אחרת, יכול להיות שהקובץ המצורף הזה הועתק מפריט אחר בשידור או מקורס אחר. במדריך טיפול בתוכן שהועתק יש המלצות לגבי התרחיש הזה.

פרטי העבודה שהוגשה על ידי התלמיד או התלמידה

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

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 חייב להיות חיובי.
• התוסף חייב להיות היוצר המקורי של הקובץ המצורף.

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

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

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

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

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

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

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

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

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

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

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

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

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