מורים שמשתמשים גם ב-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.
כל השדות שזמינים במשאבי התלמיד והמורה מפורטים במסמכי התיעוד שלהם. שני השדות הנפוצים ביותר, שנדרשים בדרך כלל, הם השדות 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
- מספק גישת קריאה למאפיין האימייל של מורים ותלמידים
סנכרון של רשימות משתמשים עם התראות Pub/Sub
במהלך שנת הלימודים, רשימות התלמידים עשויות להשתנות כשתלמידים מפסיקים ללמוד בקורסים או מצטרפים לקורסים. הוספה של התראות Pub/Sub תאפשר לכם לשמור על סנכרון בין האפליקציה של הצד השלישי לבין רשימות התלמידים ב-Classroom. כדי לקבל התראות, צריך להגדיר נושא ב-Google Cloud Pub/Sub ואז לרשום את הנושא ב-Classroom API. ההרשמה הזו היא בקשה ל-Classroom לשלוח נתונים מהפיד שצוין לנושא שצוין. הפיד הזה יהיה טריגר לאירועים של סנכרון מחדש עם רשימת התלמידים בכיתה של מורה.
כדי להשתמש בהתראות פוש, צריך להוסיף עוד היקף הרשאות שלא צריך לשלוח לאימות:
- https://www.googleapis.com/auth/classroom.push-notifications
- מאפשר לאפליקציה להירשם לכל פעילות של התראות פוש
פרטים נוספים על שילוב עם התראות פוש ב-Classroom זמינים במדריך בנושא ניהול התראות פוש.