התראות ב-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 מתקבלות התראות רק לגבי משאבים שאתם יכולים להציג באמצעות פרטי הכניסה שאתם מספקים בזמן ההרשמה. לדוגמה, אם המשתמש מבטל את ההרשאה מהאפליקציה או הוסר כמורה, ההתראות נשלחות לזמן ארוך יותר.

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

בשלב זה, ממשק ה-API של Classroom מציע שלושה סוגי עדכונים:

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

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

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

כדי להגדיר נושא ב-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 יש הרשאה רק למספר מוגבל של נושאים, לכן שימוש בנושא אחד לקבלת כל ההתראות מבטיח שלא תיפגעו בבעיות של התאמה לעומס (scaling) אם האפליקציה שלכם הופכת לפופולרית.

  5. ליצור מינוי ב-Cloud Pub/Sub ולהורות ל-Cloud Pub/Sub איך לשלוח את ההתראות.

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

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

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

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

הרשאות

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

  • כשמדובר בפידים של שינויים בהרכבים, זה אומר שמדובר בהיקף של רשימת האומנים, או (עדיף) בווריאציה לקריאה בלבד (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 יאוכלסו בשדות courseId ו-userId ללא שינוי, ואפשר יהיה לשלוח אותם ללא שינוי ל-courses.students.get() או ל-courses.teachers.get(). בדומה, גם בשדות של הקורסים.coursework אוסף השדות courseId ו-id אפשר לשלוח את השדות courseId ו-id ללא שינוי, אל courses.courseWork.get(), ו-subcourses unmodified() subcourses.Submission() ו-subsubmission המח הילדים כיcourseWorkIdcourses.courseWork.studentSubmissions.get()

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

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

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