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