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

בדף הזה מופיעה סקירה כללית על האופן שבו פועלות בקשות ב-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() צריך לציין:

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