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

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

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

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

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

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

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

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

• בקובץ המצורף צריך להיות ערך maxPoints חיובי.
• התוסף חייב להיות היוצר המקורי של הקובץ המצורף.

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

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

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

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

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

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

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

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

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

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

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

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

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

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