מורים שמשתמשים גם ב-Classroom וגם בכלים של צד שלישי נתקלים בבעיה של הגדרת הקורסים ורשימות התלמידים בכמה פלטפורמות. אפשר לעשות את זה באופן ידני, באמצעות העלאה של קובצי CSV או הזנה של כתובות אימייל אחת-אחת. עם זאת, באמצעות Classroom API, כלי צד שלישי יכולים להפחית את עומס העבודה של המורים על ידי שילוב עם תרחיש השימוש הנפוץ ביותר של ה-API: ייבוא רשימת תלמידים.
ייבוא של רשימות התלמידים מאפשר לפלטפורמות של צד שלישי לאחזר מטא-נתונים של קורס, מורים ותלמידים בקורס, עם הרשאות של מורה או אדמין. מורים יכולים לאחזר פרטים על הקורסים שהם מלמדים, ואילו לאדמינים יש גישה לפרטים של כל הקורסים בכל הדומיין. הגמישות הזו מאפשרת למפתחים להעביר בקלות את רשימות התלמידים ב-Classroom לפלטפורמה שלהם, ברמה של מורה ספציפי או ברמת הדומיין כולו, באמצעות פרטי כניסה של אדמין.
לפני שנעמיק בפרטים הטכניים של שילוב ייבוא רשימת תלמידים, נסקור קודם דוגמה לתהליך עבודה:
באפליקציה של צד שלישי, איש/אשת הוראה בוחרים באפשרות לייבא קורס ב-Classroom.
האפליקציה של צד שלישי קוראת ל-method
courses.listדרך Classroom API, שתחזיר תגובה בפורמט JSON עם כל הקורסים של המורה.מתוך תגובת ה-JSON, האפליקציה של הצד השלישי מציגה את שמות הקורסים של המורה כדי שהמורה יוכל לבחור קורס. כדי להמשיך לשלב הבא, האפליקציה צריכה לעקוב אחרי מזהי הקורסים.
בעזרת מזהה הקורס שנבחר, האפליקציה של הצד השלישי קוראת לשיטות
students.listו-teachers.listומציגה את כל השמות באתר שלה כדי שהמורים יוכלו לאשר את הייבוא.באמצעות האימיילים שמוחזרים בקובצי ה-JSON של התגובה
students.listו-teachers.list, אפליקציית הצד השלישי מזמינה את המשתמשים להצטרף לקורס החדש שיובא בפלטפורמה שלה.
לכל אחת מהשיטות שמוזכרות בתהליך העבודה, אפשר להשתמש ב-API Explorer כדי לראות בדיוק איך כל שיטה מתנהגת. מומלץ גם לקרוא את המאמרים הבאים לפני שמסיימים את המדריך הזה:
תחילת העבודה
לפני שמיישמים את הפרטים של ייבוא רשימת התלמידים ב-Classroom, צריך לקבוע אילו פרטי קורס ומשתמשים צריך לאחזר באמצעות ה-API. אפשר לראות אילו מטא-נתונים של קורסים זמינים במסמכי העיון, אבל בהמשך מופיע סיכום של כמה שדות נדרשים או נפוצים:
| שדה | שימוש |
|---|---|
| id [מזהה] | נדרש לבקשות API לאחזור נתונים של תלמידים או מורים |
| שם | מומלץ לשימוש קל למשתמש, כלומר להצגה באתר |
| ownerId | נדרש כשמייבאים ברמת הדומיין כדי לזהות נכון את המורה הראשי בקורס |
פרטי הקורס האלה מאוחזרים בשלב courses.list בתהליך העבודה שלמעלה. בבקשה הזו אפשר לציין פרמטרים מסוימים של הבקשה. אף אחד מהם לא נדרש לשיטה הזו, אבל הנה כמה פרמטרים מומלצים:
| פרמטר | שימוש |
|---|---|
| courseState | אם לא מציינים את המצב, ה-API יחזיר קורסים מכל ששת מצבי הקורס. מומלץ לציין ACTIVE כדי לאחזר את הקורסים שבהם המורים משתמשים כרגע. |
| pageSize | למורים שמייבאים קורסים משלהם, מומלץ לציין ערך קטן (פחות מ-10) של pageSize כדי לקצר את זמן התגובה של קריאת ה-API. |
| pageToken | חובה אם משתמשים בבקשות עם חלוקה לדפים. |
| teacherId | מומלץ כי אדמינים של דומיין לרוב מלמדים קורסים. אם לא מציינים את ההגדרה הזו, הבקשה תחזיר קורסים למורים בכל הדומיין. |
| Fields | מומלץ להפחית את זמן התגובה של קריאת ה-API. |
בעזרת מזהי הקורסים שאוחזרו קודם, האפליקציה יכולה עכשיו לאחזר את רשימת התלמידים והמורים העמיתים בקורס או בקורסים האלה. מזהה הקורס הוא פרמטר השאילתה היחיד שנדרש עבור teachers.list ו-students.list, אבל כדאי לשקול לציין גם את הפרמטרים pageSize ו-fields כדי לקצר את זמן התגובה של קריאות ה-API.
כל השדות שזמינים במשאבי student ו-teacher מפורטים במסמכים הרלוונטיים. שני השדות הנפוצים ביותר, שנדרשים בדרך כלל, נמצאים בשדה profile: profile.name ו-profile.emailAddress.
| שדה | שימוש |
|---|---|
| profile.name | מומלץ לשימוש קל למשתמש, כלומר להצגה באתר |
| profile.emailAddress | נדרש לאפליקציות שמחפשות דרך ייחודית לזיהוי תלמידים |
כדי לאחזר ולהשתמש בפרטים האלה של הקורס או רשימת התלמידים מ-Classroom, האפליקציה שלכם תצטרך לבקש הרשאה מהמשתמשים. כדי להטמיע את תהליך העבודה הזה, צריך להגדיר שלושה (3) היקפי הרשאות:
- https://www.googleapis.com/auth/classroom.courses.readonly
- ההרשאה מספקת גישת קריאה בלבד לקורסים ב-Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- ההרשאה מאפשרת גישת קריאה בלבד לרשימות התלמידים בקורסים ב-Google Classroom (מורים ותלמידים)
- https://www.googleapis.com/auth/classroom.profile.emails
- מספק גישת קריאה למאפיין email של מורים ותלמידים
סנכרון של רשימות משתמשים עם התראות Pub/Sub
במהלך שנת הלימודים, יכול להיות שרשימות התלמידים ישתנו כי תלמידים יפסיקו ללמוד בקורסים או יצטרפו לקורסים. הוספה של התראות Pub/Sub תאפשר לכם לשמור על סנכרון בין האפליקציה של הצד השלישי לבין רשימות התלמידים ב-Classroom. כדי לקבל התראות, צריך להגדיר נושא ב-Google Cloud Pub/Sub ואז לרשום את הנושא ב-Classroom API. ההרשמה הזו היא בקשה ל-Classroom לשלוח נתונים מהפיד שצוין לנושא שצוין. הפיד הזה יהיה טריגר האירועים לסנכרון מחדש עם רשימת התלמידים של מורה ב-Classroom.
כדי להשתמש בהתראות פוש, צריך להוסיף עוד היקף הרשאה שלא צריך לשלוח לאימות:
- https://www.googleapis.com/auth/classroom.push-notifications
- מאפשר לאפליקציה להירשם לכל פעילות של התראות פוש
לפרטים נוספים על שילוב עם התראות פוש ב-Classroom, אפשר לעיין במדריך שלנו בנושא ניהול התראות פוש.