اعلان‌های فشاری در Classroom API

می توانید از روش های موجود در مجموعه Registrations برای دریافت اعلان ها هنگام تغییر داده ها در Classroom استفاده کنید.

این مقاله یک نمای کلی مفهومی به همراه دستورالعمل های ساده در مورد نحوه شروع دریافت اعلان های فشار ارائه می دهد.

نمای کلی اعلان‌های فشاری کلاس

ویژگی اعلان‌های فشاری API Classroom به برنامه‌هایی که از Classroom API استفاده می‌کنند اجازه می‌دهد تا در صورت تغییر داده‌ها در Classroom، برای اعلان‌ها مشترک شوند. اعلان‌ها معمولاً ظرف چند دقیقه پس از تغییر به یک موضوع Cloud Pub/Sub ارسال می‌شوند.

برای دریافت اعلان‌های فشاری، باید یک موضوع Cloud Pub/Sub راه‌اندازی کنید و نام آن موضوع را هنگام ایجاد ثبت‌نام برای فید مناسب اعلان‌ها ارائه کنید.

در زیر تعاریف مفاهیم کلیدی مورد استفاده در این مستندات آورده شده است:

  • مقصد مکانی است که اعلان ها در آن ارسال می شود.
  • فید نوعی اعلان است که یک برنامه شخص ثالث می تواند در آن مشترک شود. به عنوان مثال، "تغییر فهرست برای دوره 1234".
  • ثبت‌نام دستورالعملی است به Classroom API برای ارسال اعلان‌ها از یک فید خاص به یک مقصد .

هنگامی که یک ثبت نام برای یک فید ایجاد می کنید، موضوع Cloud Pub/Sub آن ثبت، اعلان هایی را از آن فید دریافت می کند تا زمانی که منقضی شود. ثبت‌نام شما یک هفته طول می‌کشد، اما می‌توانید در هر زمانی قبل از انقضا آن را با درخواستی مشابه برای registrations.create() تمدید کنید.

موضوع Cloud Pub/Sub شما فقط اعلان‌هایی درباره منابعی دریافت می‌کند که می‌توانید با اعتبارنامه‌هایی که هنگام ایجاد ثبت نام ارائه می‌دهید مشاهده کنید. برای مثال، اگر کاربر مجوز برنامه شما را لغو کند یا به عنوان معلم حذف شود، اعلان‌ها طولانی‌تر ارسال می‌شوند.

انواع خوراک

Classroom API در حال حاضر سه نوع فید ارائه می دهد:

  • هر دامنه دارای تغییرات فهرستی برای فید دامنه است که هنگام پیوستن و ترک دوره های آموزشی در آن دامنه، اعلان هایی را نشان می دهد.
  • هر دوره دارای تغییرات فهرستی برای فید دوره است که هنگام پیوستن و خروج دانش آموزان و معلمان به دوره های آن دوره، اعلان ها را نشان می دهد.
  • هر دوره دارای تغییراتی در کار درسی برای فید دوره است، که هنگام ایجاد یا تغییر هر کار درسی یا اشیاء ارسالی دانشجو در آن دوره، اعلان‌هایی را نشان می‌دهد.

راه اندازی یک موضوع Cloud Pub/Sub

اعلان‌ها به موضوعات Cloud Pub/Sub ارسال می‌شوند. از Cloud Pub/Sub، می‌توانید اعلان‌ها را در یک قلاب وب یا با نظرسنجی نقطه پایانی اشتراک دریافت کنید.

برای تنظیم یک موضوع Cloud Pub/Sub، باید موارد زیر را انجام دهید:

  1. مطمئن شوید که پیش نیازهای Cloud Pub/Sub را برآورده کرده اید.
  2. یک کلاینت Cloud Pub/Sub راه اندازی کنید .
  3. قیمت گذاری Cloud Pub/Sub را مرور کنید و صورتحساب پروژه Developer Console خود را فعال کنید.

  4. یک موضوع Cloud Pub/Sub در Developer Console (ساده ترین)، از طریق ابزار خط فرمان (برای استفاده ساده برنامه ریزی شده) یا با استفاده از Cloud Pub/Sub API ایجاد کنید. توجه داشته باشید که Cloud Pub/Sub تنها به تعداد محدودی از موضوعات اجازه می‌دهد ، بنابراین استفاده از یک موضوع برای دریافت تمام اعلان‌های خود تضمین می‌کند که در صورت محبوب شدن برنامه‌تان، با مشکلات مقیاس‌پذیری مواجه نشوید.

  5. یک اشتراک در Cloud Pub/Sub ایجاد کنید تا به Cloud Pub/Sub بگویید چگونه اعلان‌های خود را تحویل دهد.

  6. در نهایت، قبل از ثبت نام برای Push Notifications، باید به حساب سرویس Push Notifications ( classroom-notifications@system.gserviceaccount.com ) اجازه انتشار در موضوع خود بدهید .

توجه: اگر به حساب سرویس Push Notifications اجازه انتشار در موضوع Cloud Pub/Sub خود بدهید، کاربرانی که می‌توانند از پروژه Developer Console شما درخواست کنند، می‌توانند وجود آن را تشخیص دهند و برای اعلان‌های مربوط به آن ثبت‌نام کنند. بسیاری از برنامه‌ها شناسه‌های سرویس گیرنده OAuth را در سمت کلاینت ذخیره می‌کنند، بنابراین کاربران نهایی ممکن است بتوانند از پروژه کنسول برنامه‌نویس شما درخواست کنند. اگر این در مورد شما صدق می‌کند و نگران ارسال اعلان‌های ناخواسته توسط کاربران نهایی به موضوع Cloud Pub/Sub خود هستید یا نام موضوعات Cloud Pub/Sub را که برای اعلان‌های فشار استفاده می‌کنید، می‌دانید، باید ثبت‌نام برای Push Notifications را در نظر بگیرید. پروژه های مختلف Developer Console.

درخواست خود را برای اطلاعیه ها ثبت کنید

هنگامی که موضوعی دارید که حساب سرویس اعلان‌های فشار API Classroom می‌تواند در آن منتشر کند، می‌توانید با استفاده از روش registrations.create() برای اعلان‌ها ثبت نام کنید. متد registrations.create() تأیید می‌کند که می‌توان به موضوع Cloud Pub/Sub ارائه‌شده توسط حساب سرویس push notifications دسترسی پیدا کرد. اگر حساب سرویس اعلان‌های فشار نتواند به موضوع دسترسی پیدا کند، این روش با شکست مواجه می‌شود. برای مثال، اگر موضوع وجود نداشته باشد یا به آن اجازه انتشار در آن موضوع را نداده باشید.

مجوز

مانند همه تماس‌های API Classroom، فراخوان‌های 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() برای لغو ثبت از اعلان‌ها استفاده کرد.