شما میتوانید از متدهای موجود در مجموعه Registrations برای دریافت اعلانها هنگام تغییر دادهها در Classroom استفاده کنید.
این مقاله یک مرور کلی مفهومی به همراه دستورالعملهای ساده در مورد نحوه شروع دریافت اعلانهای فوری ارائه میدهد.
نمای کلی اعلانهای فوری کلاس درس
قابلیت اعلانهای API کلاس درس به برنامههایی که از API کلاس درس استفاده میکنند اجازه میدهد تا هنگام تغییر دادهها در کلاس درس، مشترک اعلانها شوند. اعلانها معمولاً ظرف چند دقیقه پس از تغییر، به یک موضوع Cloud Pub/Sub ارسال میشوند.
برای دریافت اعلانهای فوری، باید یک موضوع Cloud Pub/Sub تنظیم کنید و هنگام ایجاد ثبتنام برای فید اعلانهای مربوطه، نام آن موضوع را ارائه دهید.
در زیر تعاریف مفاهیم کلیدی مورد استفاده در این سند آمده است:
- مقصد جایی است که اعلانها به آنجا ارسال میشوند.
- فید نوعی اعلان است که یک برنامه شخص ثالث میتواند در آن مشترک شود. برای مثال، "تغییرات فهرست دروس برای دوره ۱۲۳۴".
- ثبت نام، دستورالعملی به Classroom API است تا اعلانها را از یک فید خاص به یک مقصد ارسال کند.
وقتی برای یک فید ثبتنام میکنید، موضوع Cloud Pub/Sub مربوط به آن ثبتنام تا زمان انقضا از آن فید اعلان دریافت میکند. ثبتنام شما یک هفته اعتبار دارد، اما میتوانید با ارسال درخواستی مشابه به registrations.create() آن را در هر زمانی قبل از انقضا تمدید کنید.
موضوع Cloud Pub/Sub شما فقط اعلانهایی درباره منابعی دریافت میکند که میتوانید با اعتبارنامههایی که هنگام ایجاد ثبتنام ارائه میدهید، مشاهده کنید. به عنوان مثال، اگر کاربر مجوز برنامه شما را لغو کند یا به عنوان معلم حذف شود، اعلانها دیگر ارسال نمیشوند.
انواع خوراکها
رابط برنامهنویسی کاربردی کلاس درس سه نوع فید ارائه میدهد:
- هر دامنه دارای یک فهرست تغییرات برای فید دامنه است که هنگام ورود و خروج دانشآموزان و معلمان به دورههای آن دامنه، اعلانهایی را نمایش میدهد.
- هر دوره دارای یک تغییر در فهرست دروس است که هنگام ورود و خروج دانشآموزان و معلمان به دورههای آن دوره، اعلانهایی را نمایش میدهد.
- هر دوره دارای یک فید تغییرات کار دوره برای دوره است که در صورت ایجاد یا تغییر هرگونه کار دوره یا اشیاء ارسالی دانشجو در آن دوره، اعلانهایی را نمایش میدهد.
یک موضوع فرعی/میخانه ابری تنظیم کنید
اعلانها به موضوعات Cloud Pub/Sub ارسال میشوند. از Cloud Pub/Sub، میتوانید اعلانها را از طریق وبهوک یا با نظرسنجی از یک نقطه پایانی اشتراک دریافت کنید.
برای تنظیم یک موضوع Cloud Pub/Sub، باید موارد زیر را انجام دهید:
- مطمئن شوید که پیشنیازهای Cloud Pub/Sub را برآورده کردهاید.
- یک کلاینت Cloud Pub/Sub راهاندازی کنید .
- قیمتگذاری Cloud Pub/Sub را بررسی کنید و صورتحساب را برای پروژه Developer Console خود فعال کنید.
یک موضوع Cloud Pub/Sub در کنسول توسعهدهندگان (سادهترین)، از طریق ابزار خط فرمان (برای استفاده ساده برنامهنویسی) یا با استفاده از API Cloud Pub/Sub ایجاد کنید. توجه داشته باشید که Cloud Pub/Sub فقط تعداد محدودی از موضوعات را مجاز میداند ، بنابراین استفاده از یک موضوع برای دریافت همه اعلانهای شما تضمین میکند که در صورت محبوبیت برنامهتان، با مشکلات مقیاسپذیری مواجه نشوید.
یک اشتراک در Cloud Pub/Sub ایجاد کنید تا به Cloud Pub/Sub بگویید چگونه اعلانهای شما را ارسال کند.
در نهایت، قبل از ثبت نام برای دریافت اعلانهای فوری، باید به حساب کاربری سرویس اعلانهای فوری (
classroom-notifications@system.gserviceaccount.com) اجازه انتشار در موضوع خود را بدهید .
درخواست خود را برای دریافت اعلانها ثبت کنید
وقتی موضوعی دارید که حساب سرویس اعلانهای فشاری Classroom API میتواند در آن منتشر شود، میتوانید با استفاده از متد registrations.create() برای اعلانها ثبت نام کنید. متد registrations.create() تأیید میکند که حساب سرویس اعلانهای فشاری میتواند به موضوع Cloud Pub/Sub ارائه شده دسترسی داشته باشد. اگر حساب سرویس اعلانهای فشاری نتواند به موضوع دسترسی پیدا کند، این روش با شکست مواجه میشود. به عنوان مثال، اگر موضوع وجود نداشته باشد یا شما مجوز انتشار در آن موضوع را به آن نداده باشید.
مجوز
مانند تمام فراخوانیهای Classroom API، فراخوانیهای registrations.create() باید با یک توکن مجوزدهی مجاز شوند . این توکن احراز هویت باید شامل محدوده اعلانهای ارسالی ( https://www.googleapis.com/auth/classroom.push-notifications ) و هر محدودهای که برای مشاهده دادههای مربوط به اعلانهای ارسالی مورد نیاز است، باشد.
- برای فیدهای تغییر فهرست، این به معنای محدوده فهرستها یا (در حالت ایدهآل) نوع فقط خواندنی آن است (
https://www.googleapis.com/auth/classroom.rosters.readonlyیاhttps://www.googleapis.com/auth/classroom.rosters). - برای فیدهای تغییر کار دوره، این به معنای نسخههای «دانشآموزی» از محدوده کار دوره یا (در حالت ایدهآل) نوع فقط خواندنی آن است (
https://www.googleapis.com/auth/classroom.coursework.students.readonlyیاhttps://www.googleapis.com/auth/classroom.coursework.students).
برای اینکه اعلانها ارسال شوند، برنامه باید مجوز OAuth را از کاربر مجاز با محدودههای مورد نیاز حفظ کند. اگر کاربر اتصال برنامه را قطع کند، اعلانها متوقف میشوند. توجه داشته باشید که در حال حاضر، واگذاری اختیارات در سطح دامنه برای این منظور پشتیبانی نمیشود. اگر سعی کنید اعلانها را فقط با استفاده از اختیارات واگذار شده در سطح دامنه ثبت کنید، خطای @MissingGrant دریافت خواهید کرد.
دریافت اعلانها
اعلانها با JSON کدگذاری میشوند و شامل موارد زیر هستند:
- نام مجموعهای که شامل منبعی است که تغییر کرده است. برای اعلانهای مربوط به تغییرات فهرست، این میتواند
courses.studentsیاcourses.teachersباشد. برای تغییرات کار دوره، این میتواندcourses.courseWorkیاcourses.courseWork.studentSubmissionsباشد. - شناسههای منبعی که تغییر کرده است، در یک نقشه. این نقشه به گونهای طراحی شده است که با آرگومانهای متد
getمنبع مناسب مطابقت داشته باشد. برای اعلانهای مربوط به تغییرات فهرست، فیلدهایcourseIdوuserIdپر میشوند و میتوانند بدون تغییر به courses.students.get() یا courses.teachers.get() ارسال شوند. به طور مشابه، تغییرات در مجموعه courses.courseWork دارای فیلدهایcourseIdوidخواهند بود که میتوانند بدون تغییر به courses.courseWork.get() ارسال شوند و تغییرات در مجموعه courses.courseWork.studentSubmissions دارای فیلدهایcourseId،courseWorkIdوidخواهند بود که میتوانند بدون تغییر به courses.courseWork.studentSubmissions.get() ارسال شوند.
قطعه کد زیر یک نمونه اعلان را نشان میدهد:
{
"collection": "courses.students",
"eventType": "CREATED",
"resourceId": {
"courseId": "12345",
"userId": "45678"
}
}
اعلانها همچنین دارای یک ویژگی پیام registrationId هستند که شامل شناسهای برای ثبت نامی است که باعث ایجاد اعلان شده است، که میتواند با registrations.delete() برای لغو ثبت نام از اعلانها استفاده شود.