מורים שמשתמשים גם בכלים של Classroom וגם בכלים של צד שלישי מתמודדים עם האתגר של הגדרת הקורסים ורשימות התלמידים בפלטפורמות שונות. אפשר לעשות את זה באופן ידני באמצעות העלאות בקובץ CSV או להזין הודעות אימייל אחת אחרי השנייה. עם זאת, בעזרת Classroom API, כלים של צד שלישי יכולים להפחית את עומסי העבודה של המורים באמצעות שילוב עם התרחיש הנפוץ ביותר לשימוש ב-API: ייבוא רשימת תלמידים.
ייבוא של רשימות תלמידים מאפשר לפלטפורמות של צד שלישי לאחזר את המטא-נתונים, המורים והתלמידים של הקורס, עם הרשאות מורים או הרשאות אדמין לכל קורס בנפרד. מורים יכולים לאחזר פרטים על הקורסים שהם מלמדים, ואילו לאדמינים יש גישה לפרטים של כל הקורסים בדומיין שלם. הגמישות הזו מאפשרת למפתחים לצרף בצורה חלקה רשימות תלמידים ל-Classroom לפלטפורמה שלהם, גם ברמת המורה האישי וגם ברמת הדומיין כולו, באמצעות פרטי כניסה של אדמין.
לפני שנפרט את הפרטים הטכניים על השילוב של ייבוא רשימות תלמידים, כדאי לסקור קודם את תהליך העבודה לדוגמה:
באפליקציית הצד השלישי, המורה בוחר באפשרות לייבא קורס ב-Classroom.
אפליקציית הצד השלישי מפעילה את השיטה
courses.listדרך Classroom API, וכך היא תחזיר קובץ JSON עם כל הקורסים של המורה.מתוך תגובת ה-JSON, אפליקציית הצד השלישי מציגה את שמות הקורסים של המורה כדי שהם יוכלו לבחור אחד מהם. כדי להמשיך לשלב הבא, האפליקציה צריכה לעקוב אחרי מזהי הקורס.
באמצעות מזהה הקורס שנבחר, אפליקציית הצד השלישי קוראת ל-method
students.listו-teachers.listומציגה את כל השמות באתר שלה כדי שהמורים יאשרו את הייבוא.באמצעות כתובות האימייל שהוחזרו ב-JSON של התגובה
students.listו-teachers.list, אפליקציית הצד השלישי מזמינה את המשתמשים להצטרף לפלטפורמה של הקורס החדש שיובא.
בכל אחת מהשיטות שמוזכרות בתהליך העבודה, אפשר להשתמש ב-API Explorer כדי לבדוק בדיוק איך כל שיטה פועלת. מומלץ גם לקרוא את הקריאות הבאות לפני שמסיימים את המדריך:
תחילת העבודה
לפני שתטמיעו את הפרטים הספציפיים של ייבוא רשימות התלמידים ב-Classroom, עליכם להחליט אילו פרטים לגבי הקורסים ולגבי המשתמשים צריך לאחזר דרך ה-API. במסמכי העזר תוכלו לראות אילו מטא-נתונים של הקורס זמינים, אבל אפשר לסכם חלק מהשדות הנפוצים או הנדרשים:
| שדה | שימוש |
|---|---|
| id | נדרש עבור בקשות API לאחזור תלמידים או מורים |
| name | מומלץ למשתמשים כדי שיהיה קל להשתמש בהם, למשל להציג אותם באתר שלכם. |
| ownerId | נדרשת כשמייבאים נתונים ברמת הדומיין כדי לזהות נכון את המורה הראשי/ת בקורס. |
המידע על הקורס מאוחזר בשלב courses.list של תהליך העבודה שלמעלה. בבקשה הזו אפשר לציין פרמטרים מסוימים של בקשה. אמנם לא חובה להשתמש בשיטה הזו, אבל כמה מהפרמטרים המומלצים הם:
| פרמטר | שימוש |
|---|---|
| courseState | אם לא מציינים שום אפשרות, ה-API יחזיר קורסים מכל ששת מצבי הקורס. מומלץ לציין את הקורס ACTIVE כדי לאחזר את הקורסים שבהם המורים משתמשים. |
| pageSize | למורים שמייבאים קורסים משלהם, מומלץ לציין pageSize קטן (פחות מ-10) כדי לקצר את זמן התגובה של הקריאה ל-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
- מספקים גישת קריאה לנכס email של מורים ותלמידים
סנכרון של רשימות התלמידים עם התראות Pub/Sub
עם התקדמות שנת הלימודים, רשימות התלמידים עשויות להשתנות כאשר תלמידים מפסיקים או מוסיפים קורסים. הוספה של התראות ב-Pub/Sub תאפשר לכם לסנכרן את האפליקציה של הצד השלישי עם סרגלי הקהלים ב-Classroom. כדי לקבל התראות, צריך להגדיר נושא ב-Google Cloud Pub/Sub ולאחר מכן לרשום את הנושא באמצעות Classroom API. ההרשמה הזו היא בקשה ל-Classroom לשלוח נתונים מהפיד הנתון לנושא הנתון. הפיד הזה ישמש כטריגרים לאירוע, לצורך סנכרון מחדש עם רשימת התלמידים ב-Classroom של המורה.
לשימוש בהתראות נדרש היקף אחד נוסף, שלא צריך להגיש לאימות:
- https://www.googleapis.com/auth/classroom.push-notifications
- מאפשרת לאפליקציה להירשם לכל פעילות של התראות שנשלחות מהאפליקציה
במדריך שלנו לניהול התראות ב-Classroom מפורט מידע נוסף על השילוב עם ההתראות של Classroom.