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

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

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

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