מבוא

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

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

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

  1. באפליקציה של הצד השלישי, המורה בוחר באפשרות לייבא קורס מ-Classroom.

  2. אפליקציית הצד השלישי קוראת ל-method‏ courses.list דרך Classroom API, שמחזיר תגובה בפורמט JSON עם כל הקורסים של המורה.

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

  4. באמצעות מזהה הקורס שנבחר, האפליקציה של הצד השלישי קוראת לשיטות students.list ו-teachers.list ומציגה את כל השמות באתר שלה כדי שהמורים יוכלו לאשר את הייבוא.

  5. באמצעות כתובות האימייל שמוחזרות ב-JSON של התשובות students.list ו-teachers.list, האפליקציה של הצד השלישי מזמינה את המשתמשים להצטרף לקורס שיובאו לאחרונה בפלטפורמה שלהם.

בכל אחת מהשיטות שצוינו בתהליך העבודה, אפשר להשתמש ב-API Explorer כדי לראות בדיוק איך כל שיטה פועלת. מומלץ גם לקרוא את המאמרים הבאים לפני שמסיימים את המדריך:

  1. ניהול קורסים באמצעות Classroom API
  2. ניהול תלמידים ומורים

תרשים שמסכם את תהליך הייבוא של רשימות התלמידים שמתואר למעלה.

תחילת העבודה

לפני שמטמיעים את פרטי הכיתה מ-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
    • הרשאת קריאה למאפיין email של מורים ותלמידים

סנכרון רשימות של משתמשים באמצעות התראות Pub/Sub

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

כדי להשתמש בהתראות דחיפה, יהיה צורך בהיקף נוסף אחד, שאין צורך לשלוח לאימות:

  • https://www.googleapis.com/auth/classroom.push-notifications
    • מאפשרת לאפליקציה להירשם לכל פעילות של התראות

תרשים שמסכם את תהליך הייבוא של רשימת התלמידים עם התראות בדחיפה

למידע נוסף על שילוב עם התראות דחיפה ב-Classroom, תוכלו לעיין במדריך לניהול התראות דחיפה.