איך פועלות הבקשות

בדף הזה מופיעה סקירה כללית של אופן הפעולה של בקשות ב-Google Classroom API. המטרה היא לעזור לקוראים שלא מכירים את העיצוב מבוסס-המשאבים או את ממשקי ה-API של Google Workspace.

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

עיצוב מבוסס-משאבים

כמו שצוין במאמר API resources, ‏ Classroom API פועל לפי דפוסי עיצוב ממוקד משאבים. לרוב המשאבים יש שיטות לפעולות סטנדרטיות כמו יצירה, קריאה, עדכון ומחיקה של מופעים של המשאב.

לדוגמה, אפשר create(), patch(), get(), list() ו-delete() Course בכיתה באמצעות ה-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() צריך לציין:

1. ה-id של מקור המידע שרוצים לשנות.
2. רשימה של שדות, שנקראת updateMask, כדי לקבוע אילו שדות במשאב צריך לעדכן. השדה הזה אופציונלי במקרים שבהם יש קבוצת שדות שמוגדרת כברירת מחדל או שהשדות מוסקים.

כדאי לדעת: יכול להיות שתראו שיטות update() לצד שיטות patch(). שתי הפעולות משנות משאב, אבל הן שונות בהתנהגות שלהן. הפעולה Update() מחליפה משאב לגמרי במשאב חדש, בעוד שהפעולה patch() מעדכנת רק שדות נבחרים. לדוגמה, הפקודה courses.update() מחליפה Course קיים שלם, ואילו הפקודה courses.patch() משתמשת ב-fieldMask שצוין כדי לשנות רק שדות ספציפיים ב-Course. כדי לפשט את התהליך, Google Classroom API משתמש כמעט אך ורק ב-patch(), ובאופן כללי מומלץ להשתמש בשיטה הזו.

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