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

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

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

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

חשוב: כששולחים בקשות 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 לא מוגדר או להגדיר אותו לאפס.

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

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

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