התראות ב-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. לסיום, לפני שרושמים את עצמכם לקבלת הודעות פוש, צריך להעניק לחשבון השירות של הודעות הפוש (classroom-notifications@system.gserviceaccount.com) הרשאה לפרסום בנושא.

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

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

אישור

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