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

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

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

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