בדף הזה מופיעה סקירה כללית על האופן שבו פועלות בקשות ב-Google Classroom API. המטרה היא לעזור לקוראים שעדיין לא מכירים את העיצוב שמתמקד במשאבים או את ממשקי ה-API של Google Workspace.
דוגמאות קוד ספציפיות מפורטות במדריכי ה-API המתאימים, למשל יצירה וניהול של קורסים או יצירה וניהול של עבודות.
עיצוב שמתמקד במשאבים
כפי שצוין בקטע מבנה ה-API, Classroom API פועל לפי דפוסים של תכנון שמתמקד במשאבים. לרוב המשאבים יש שיטות לפעולות רגילות כמו יצירה, קריאה, עדכון ומחיקה של מכונות של המשאב.
לדוגמה, אפשר create(), patch(), get(), list() וdelete() את Course ב-Classroom באמצעות ה-API.
יצירה
כדי ליצור משאב חדש, כמו Course, צריך להפעיל את השיטה create() של המשאב המתאים.
בקריאות ל-Create() תמיד נדרשים הפרטים הראשוניים והחיוניים של המשאב התואם כקלט. לדוגמה, כדי ליצור Course, צריך להפעיל את השיטה create() במשאב Course ולציין את name ו-description בבקשה, יחד עם מידע אופציונלי כמו room.
במשאבים משניים (שנקראים לפעמים משאבים צאצאים), נדרשים גם מזהים של המשאב ההורה. לדוגמה, כשיוצרים CourseWork בתוך Course, צריך את Course id כדי לקבוע לאיזה Course ה-CourseWork שייך.
שיטות Create() מחזירות מופע של המשאב החדש שנוצר בתגובה להפעלת ה-API. בדרך כלל, המשאב המוחזר כולל שדות נוספים שנוצרו על ידי השרת, כמו המשאב id או creationTime.
תיקון
כדי לשנות משאבים קיימים, צריך לבצע קריאה ל-method patch() (שנקרא לפעמים update()) במשאב המתאים. השיטה patch() כמעט זהה ל-create(), עם שני הבדלים עיקריים. כשקוראים לשיטה patch() צריך לציין:
- ה-
idשל המשאב שרוצים לשנות. - רשימת שדות, שנקראת
updateMask, כדי לקבוע אילו שדות במשאב צריך לעדכן. האפשרות הזו היא אופציונלית במקרים שבהם יש קבוצת שדות שמוגדרת כברירת מחדל או שהשדות מוסקים.
השיטות Patch() מחזירות את המופע המלא של המשאב המעודכן בתגובה לשיחה ב-API, עם כל השינויים שבוצעו.
אחזור ורישום
יש שתי שיטות לאחזור משאבים: get() ו-list().
השיטה get() מאחזרת משאב ספציפי לפי מזהה כלשהו. לדוגמה, אחזור של Course על סמך id או alias. קריאה ל-get() מחזירה את המשאב המלא ישירות.
השיטה list() מאחזרת כמה משאבים מאותו סוג בבקשה אחת, בלי צורך במזהי המשאבים הנפרדים. לרוב, הפעולה list() מקבלת את כל משאבי המשנה של משאב הורה כלשהו. לדוגמה, אחזור של כל ה-CourseWork בתוך Course. האפשרות הזו שימושית כדי לצמצם את מספר הבקשות, בהשוואה לביצוע מספר קריאות ל-get(), והיא חשובה במיוחד כשלא ידוע לכם מהם הערכים של id של המשאבים הרצויים.
באופן כללי, לשיטות list() יש כמות מקסימלית של משאבים שאפשר להחזיר בקריאה אחת, ואפשר להגדיר מגבלות נמוכות יותר על ידי צירוף ערך pageSize לקריאה. במקרים שבהם יש יותר משאבים מהמגבלה, השיטה list() תומכת בחלוקה לדפים. כל 'דף' של תוצאות שמוחזר מספק pageToken, שאפשר לכלול בקריאה הבאה ל-list() כדי לאחזר את הקבוצה הבאה של המשאבים.
מחיקה
השיטה delete() מקבלת מזהה משאב, כמו id, ומוחקת את המשאב התואם. אם הפעולה delete() מסתיימת בהצלחה, מוחזר תשובה ריקה.
פעולות אחרות
לא כל הפעולות שאפשר לבצע באמצעות Classroom API אפשר לבצע באמצעות הפעולות הרגילות שצוינו למעלה. לדוגמה, אי אפשר לשנות את המשתמש שהוקצה למשאב CourseWork. במקרים כאלה, יש שיטות בהתאמה אישית, כמו השיטה modifyAssignees. ההתנהגות של השיטות האלה מותאמת אישית, וצריך לעיין במסמכים שלהן בנפרד.