درخواست ها چگونه کار می کنند

این صفحه نمای کلی سطح بالایی از نحوه عملکرد درخواست‌ها در Google Classroom API را شرح می‌دهد. هدف کمک به خوانندگانی است که از قبل با طراحی منبع گرا یا APIهای Google Workspace آشنا نیستند.

برای نمونه کدهای خاص، راهنمای API مربوطه را ببینید، برای مثال ایجاد و مدیریت دوره‌ها یا ایجاد و مدیریت دوره‌های آموزشی .

طراحی منبع محور

همانطور که در ساختار API ذکر شد، API Classroom از الگوهای طراحی منبع گرا پیروی می کند. اکثر منابع دارای روش هایی برای عملیات استاندارد مانند ایجاد، خواندن، به روز رسانی و حذف نمونه های منبع هستند.

به عنوان مثال، می‌توان با استفاده از API یک Course کلاس را create() , patch() , get() , list() و delete() .

ایجاد کنید

برای ایجاد یک منبع جدید، مانند Course ، متد create() را برای منبع مربوطه فراخوانی کنید.

فراخوانی های Create() همیشه به جزئیات اولیه و حیاتی منبع مربوطه به عنوان ورودی نیاز دارند. به عنوان مثال، برای ایجاد یک Course ، متد create() را در منبع Course فراخوانی کنید و name و description در درخواست به همراه اطلاعات اختیاری مانند room مشخص کنید.

برای منابع فرعی (که گاهی منابع فرزند نامیده می شود)، شناسه های منبع والد نیز مورد نیاز است. به عنوان مثال، هنگام ایجاد یک CourseWork در یک Course ، id Course مورد نیاز است تا مشخص شود که CourseWork به کدام Course تعلق دارد.

متدهای Create() نمونه ای از منبع تازه ایجاد شده را در پاسخ فراخوانی API برمی گرداند. منبع برگشتی معمولاً دارای هر فیلد اضافی و ایجاد شده توسط سرور است، مانند id منبع یا creationTime .

پچ

برای اصلاح منابع موجود، متد 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 در دسترس هستند. رفتار این روش ها سفارشی است و شما باید مستندات مربوط به آنها را به صورت جداگانه بررسی کنید.