התראות ב-Classroom API

אפשר להשתמש בשיטות של האוסף Registrations כדי לקבל התראות כשהנתונים משתנים ב-Classroom.

במאמר הזה נספק סקירה כללית מושגית וגם הנחיות פשוטות להתחלת קבלת התראות דחיפה.

סקירה כללית על התראות הדחוף ב-Classroom

התכונה 'התראות דחיפה' של Classroom API מאפשרת לאפליקציות שמשתמשות ב-Classroom API להירשם לקבלת התראות כשיש שינויים בנתונים ב-Classroom. ההתראות נשלחות לנושא Cloud Pub/Sub, בדרך כלל תוך כמה דקות מהשינוי.

כדי לקבל התראות, צריך להגדיר נושא ב-Cloud Pub/Sub ולציין את שם הנושא כשיוצרים רישום לפיד המתאים של ההתראות.

בהמשך מפורטות הגדרות של מושגי מפתח שמופיעים במסמך הזה:

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

אחרי שיוצרים רישום של פיד, הנושא ב-Cloud Pub/Sub של הרישום הזה מקבל התראות מהפיד הזה עד שתוקף הרישום יפוג. הרישום נמשך שבוע, אבל אפשר להאריך אותו בכל שלב לפני שהתוקף שלו יפוג באמצעות שליחת בקשה זהה ל-registrations.create().

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

סוגים של פידים

כרגע יש ב-Classroom API שלושה סוגי פידים:

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

הגדרת נושא ב-Cloud Pub/Sub

ההתראות נשלחות לנושאים של Cloud Pub/Sub. ב-Cloud Pub/Sub, תוכלו לקבל התראות בהוק (hook) אינטרנט או באמצעות דגימה של נקודת קצה של מינוי.

כדי להגדיר נושא ב-Cloud Pub/Sub:

  1. חשוב לוודא שאתם עומדים בדרישות המוקדמות ל-Cloud Pub/Sub.
  2. הגדרה של לקוח Cloud Pub/Sub
  3. בודקים את המחירון של Cloud Pub/Sub ומפעילים את החיוב בפרויקט ב-Developer Console.

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

  5. יוצרים מינוי ב-Cloud Pub/Sub כדי להגדיר איך Cloud Pub/Sub יעביר את ההתראות.

  6. לסיום, לפני ההרשמה לקבלת התראות Push, צריך להעניק לחשבון השירות של התראות ה-Push (classroom-notifications@system.gserviceaccount.com) הרשאה לפרסם בנושא שלכם.

הערה: אם מעניקים לחשבון השירות של התראות ה-Push הרשאה לפרסם בנושא Cloud Pub/Sub, משתמשים שיכולים לשלוח בקשות מהפרויקט במסוף למפתחים יוכלו לקבוע שהוא קיים ולהירשם לקבלת התראות אליו. באפליקציות רבות, מזהים של לקוחות OAuth מאוחסנים בצד הלקוח, כך שמשתמשי קצה עשויים להיות מסוגלים לשלוח בקשות מהפרויקט שלכם ב-Developer Console. אם המצב הזה רלוונטי לכם ואתם חוששים שמשתמשי קצה ישלחו התראות לא רצויות לנושא Cloud Pub/Sub שלכם, או שיידעו את השמות של נושאי Cloud Pub/Sub שבהם אתם משתמשים להתראות, כדאי להירשם לקבלת התראות מפרויקט אחר במסוף הפיתוח.

רישום האפליקציה לקבלת התראות

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

אישור

בדומה לכל הקריאות ל-Classroom API, קריאות ל-registrations.create() חייבות לקבל הרשאה באמצעות אסימון הרשאה. אסימון האימות הזה חייב לכלול את ההיקף של התראות ה-Push (https://www.googleapis.com/auth/classroom.push-notifications) ואת כל ההיקפים הנדרשים כדי להציג את הנתונים לגבי ההתראות שנשלחות.

  • בפיד של שינויים ברשימות אנשי צוות, ההיקף הוא Rosters או (במצב אידיאלי) הגרסה לקריאה בלבד שלו (https://www.googleapis.com/auth/classroom.rosters.readonly או https://www.googleapis.com/auth/classroom.rosters).
  • בפיד של השינויים בעבודות בקורס, הכוונה היא לגרסאות 'תלמידים' של היקף העבודות בקורס, או (במצב אידיאלי) לגרסה לקריאה בלבד (https://www.googleapis.com/auth/classroom.coursework.students.readonly או https://www.googleapis.com/auth/classroom.coursework.students).

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

קבלת התראות

ההתראות מקודדות באמצעות JSON ומכילות:

  • השם של האוסף שמכיל את המשאב שהשתנה. להתראות על שינויים ברשימת המשתתפים, הערך הוא courses.students או courses.teachers. אם מדובר בשינויים שקשורים לעבודה, הערך הוא courses.courseWork או courses.courseWork.studentSubmissions.
  • מזהים של המשאב שהשתנה, במפה. המפה הזו מיועדת להתאים את הארגומנטים לשיטה get של המשאב המתאים. בהתראות על שינויים ברשימת התלמידים, השדות courseId ו-userId יאוכלסו וניתן יהיה לשלוח אותם ללא שינוי אל courses.students.get() או אל courses.teachers.get(). באופן דומה, שינויים באוסף courses.courseWork יכללו את השדות courseId ו-id, שניתן לשלוח אותם ללא שינוי אל courses.courseWork.get(). שינויים באוסף courses.courseWork.studentSubmissions יכללו את השדות courseId, courseWorkId ו-id, שניתן לשלוח אותם ללא שינוי אל courses.courseWork.studentSubmissions.get().

קטע הקוד הבא מדגים הודעה לדוגמה:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

להתראות יש גם מאפיין הודעה registrationId שמכיל את המזהה של הרישום שגרם להתרעה, וניתן להשתמש בו עם registrations.delete() כדי לבטל את הרישום לקבלת התראות.