התראות ב-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 יש שלושה סוגי פידים:

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

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

ההתראות מועברות לנושאים של Cloud Pub/Sub. מ-Cloud Pub/Sub אפשר לקבל התראות ב-webhook או על ידי סקירה של נקודת קצה של מינוי.

כדי להגדיר נושא ב-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() כדי לבטל את הרישום לקבלת התראות.