معلمانی که از هر دو ابزار Classroom و شخص ثالث استفاده میکنند، با چالش تنظیم دورهها و فهرستهای خود در چندین پلتفرم مواجه هستند. این کار ممکن است به صورت دستی، یا از طریق آپلود CSV یا وارد کردن ایمیلها به صورت تک تک انجام شود. با این حال، با API Classroom، ابزارهای شخص ثالث میتوانند با ادغام با رایجترین مورد استفاده API، یعنی وارد کردن فهرست، حجم کار معلمان خود را کاهش دهند.
وارد کردن فهرست به پلتفرمهای شخص ثالث اجازه میدهد تا فرادادههای یک دوره، معلمان و دانشآموزان را به صورت دوره به دوره با مجوزهای معلم یا مدیر بازیابی کنند. معلمان میتوانند جزئیات دورههایی را که تدریس میکنند بازیابی کنند، در حالی که مدیران به جزئیات همه دورهها در کل یک دامنه دسترسی دارند. این انعطافپذیری به توسعهدهندگان اجازه میدهد تا فهرستهای Classroom را به طور یکپارچه با استفاده از اعتبارنامههای مدیر، چه در سطح معلم و چه در کل دامنه، به پلتفرم خود وارد کنند.
قبل از اینکه به جزئیات فنی ادغام واردات فهرست بپردازیم، ابتدا یک نمونه گردش کار را بررسی میکنیم:
در برنامه شخص ثالث، معلم گزینه وارد کردن یک دوره کلاس درس را انتخاب میکند.
برنامهی شخص ثالث، متد
courses.listرا از طریق Classroom API فراخوانی میکند که یک JSON پاسخ شامل تمام دورههای معلم را برمیگرداند.از پاسخ json، برنامه شخص ثالث عناوین دورههای معلم را برای انتخاب یکی از آنها نمایش میدهد. برنامه برای ادامه به مرحله بعدی باید شناسههای دوره را پیگیری کند.
با شناسه دوره انتخاب شده، برنامه شخص ثالث متدهای
students.listوteachers.listرا فراخوانی میکند و تمام نامها را در وبسایت خود نمایش میدهد تا معلمان برای وارد کردن، آنها را تأیید کنند.با استفاده از ایمیلهای برگردانده شده در jsonهای پاسخ
students.listوteachers.list، برنامه شخص ثالث از کاربران دعوت میکند تا به دوره تازه وارد شده در پلتفرم خود بپیوندند.
برای هر یک از روشهای ذکر شده در گردش کار، میتوانید از API Explorer برای مشاهده دقیق نحوه عملکرد هر روش استفاده کنید. همچنین توصیه میکنیم قبل از اتمام این راهنما، مطالب زیر را مطالعه کنید:
شروع به کار
قبل از پیادهسازی جزئیات وارد کردن فهرست کلاس درس، باید مشخص کنید که چه اطلاعات دوره و کاربری را باید از طریق API بازیابی کنید. میتوانید فرادادههای دوره را در مستندات مرجع مشاهده کنید، اما برخی از فیلدهای مورد نیاز یا رایج را میتوان در زیر خلاصه کرد:
| میدان | استفاده کنید |
|---|---|
| شناسه | برای درخواستهای API جهت بازیابی دانشآموز یا معلم مورد نیاز است |
| نام | برای سهولت استفاده برای کاربر، یعنی نمایش در وبسایت شما، توصیه میشود |
| شناسه مالک | هنگام وارد کردن در سطح دامنه برای شناسایی صحیح استاد اصلی یک دوره، الزامی است |
اطلاعات این دوره در مرحله courses.list از گردش کار بالا بازیابی میشود. در این درخواست میتوانید پارامترهای درخواست خاصی را مشخص کنید. اگرچه هیچکدام برای این روش الزامی نیستند، برخی از پارامترهای توصیهشده عبارتند از:
| پارامتر | استفاده کنید |
|---|---|
| دوره ایالتی | اگر مقدار آن را مشخص نکنید، API دورههای هر شش حالت دوره را برمیگرداند. توصیه میکنیم برای بازیابی دورههایی که معلمان در حال حاضر استفاده میکنند، ACTIVE را مشخص کنید. |
| اندازه صفحه | برای معلمانی که دورههای خود را وارد میکنند، توصیه میکنیم اندازه صفحه را کوچک (کمتر از 10) تعیین کنند تا زمان پاسخگویی فراخوانی API کاهش یابد. |
| توکن صفحه | اگر از درخواستهای صفحهبندیشده استفاده میکنید، الزامی است. |
| شناسه معلم | توصیه میشود زیرا مدیران دامنه اغلب دورهها را تدریس میکنند. در صورت عدم مشخص کردن، درخواست، دورههای مربوط به معلمان در کل دامنه را برمیگرداند. |
| زمینهها | توصیه میشود زمان پاسخگویی فراخوانی API کاهش یابد. |
با استفاده از شناسههای دوره که قبلاً بازیابی شدهاند، برنامه شما اکنون میتواند لیست دانشآموزان و معلمان همکار را برای آن دوره یا دورهها بازیابی کند. این شناسه دوره تنها پارامتر پرسوجوی مورد نیاز برای teachers.list و students.list است، اما ممکن است بخواهید به طور مشابه پارامترهای pageSize و fields را برای کاهش زمان پاسخ فراخوانیهای API خود در نظر بگیرید.
تمام فیلدهای موجود برای منابع دانشآموز و معلم را میتوان در مستندات مربوطه یافت. دو فیلد پرکاربرد و مورد نیاز در فیلد profile قرار دارند: profile.name و profile.emailAddress .
| میدان | استفاده کنید |
|---|---|
| نام پروفایل | برای سهولت استفاده برای کاربر، یعنی نمایش در وبسایت شما، توصیه میشود |
| آدرس ایمیل.پروفایل | مورد نیاز برای برنامههایی که به دنبال شناسایی منحصر به فرد دانشآموزان هستند |
برای بازیابی و استفاده از هر یک از این جزئیات دوره یا فهرست از Classroom، برنامه شما باید از کاربران درخواست مجوز کند. برای پیادهسازی این گردش کار، سه (3) حوزه مورد نیاز وجود دارد:
- https://www.googleapis.com/auth/classroom.courses.readonly
- دسترسی فقط خواندنی به دورههای کلاس درس گوگل را فراهم میکند
- https://www.googleapis.com/auth/classroom.rosters.readonly
- دسترسی فقط خواندنی به فهرست دروس Google Classroom (معلمان و دانشآموزان) را فراهم میکند.
- https://www.googleapis.com/auth/classroom.profile.emails
- دسترسی خواندن به ایمیل معلمان و دانشآموزان را فراهم میکند.
همگامسازی فهرست بازیکنان با اعلانهای Pub/Sub
با پیشرفت سال تحصیلی، فهرستها ممکن است با حذف یا اضافه شدن دورهها توسط دانشآموزان تغییر کنند. افزودن اعلانهای Pub/Sub به شما این امکان را میدهد که برنامه شخص ثالث خود را با فهرستهای Classroom همگام نگه دارید. برای دریافت اعلانها، یک موضوع Google Cloud Pub/Sub تنظیم میکنید و سپس موضوع را با API Classroom ثبت میکنید. این ثبت، درخواستی برای Classroom است تا دادهها را از فید داده شده به موضوع داده شده ارسال کند. این فید، محرک رویداد برای همگامسازی مجدد با فهرست Classroom معلم خواهد بود.
استفاده از اعلانهای فشاری به یک محدوده اضافی نیاز دارد که لازم نیست برای تأیید ارسال شود:
- https://www.googleapis.com/auth/classroom.push-notifications
- به برنامه شما اجازه میدهد تا برای هرگونه فعالیت اعلانهای فوری ثبتنام کند
برای جزئیات بیشتر در مورد نحوه ادغام با اعلانهای کلاس درس، به راهنمای مدیریت اعلانهای کلاس درس ما مراجعه کنید.