تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يمكنك استخدام الطرق الواردة في مجموعة
Registrations
لتلقّي إشعارات عند تغيُّر البيانات في Classroom.
تقدّم هذه المقالة نظرة عامة على المفاهيم الأساسية، بالإضافة إلى تعليمات بسيطة حول كيفية بدء تلقّي الإشعارات الفورية.
نظرة عامة على الإشعارات الفورية في Classroom
تتيح ميزة الإشعارات الفورية في Classroom API للتطبيقات التي تستخدم
Classroom API الاشتراك في الإشعارات عند تغيير البيانات في Classroom.
يتم تسليم الإشعارات إلى موضوع 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، عليك اتّباع الخطوات التالية:
ملاحظة: إذا منحت حساب خدمة الإشعارات الفورية إذن النشر
إلى موضوع Cloud Pub/Sub، سيتمكّن المستخدمون الذين يمكنهم تقديم طلبات من مشروع Developer Console من تحديد توفّره والاشتراك لتلقّي
الإشعارات عليه. تخزِّن العديد من التطبيقات معرّفات عملاء OAuth على جانب العميل، لذا قد يتمكّن المستخدمون النهائيون من تقديم طلبات من مشروعك في Developer Console. إذا كان هذا ينطبق عليك، وكنت قلقًا بشأن إرسال المستخدمين النهائيين
إشعارات غير مرغوب فيها إلى موضوع Cloud Pub/Sub أو معرفة أسماء مواضيع
Cloud Pub/Sub التي تستخدمها للإشعارات الفورية، ننصحك
بالتسجيل للحصول على إشعارات فورية من مشروع مختلف على Developer Console.
تسجيل تطبيقك لتلقّي الإشعارات
بعد أن يكون لديك موضوع يمكن لحساب خدمة الإشعارات الفورية في 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 للمورد المناسب. بالنسبة إلى
الإشعارات حول التغييرات في القائمة، سيتمgefülltملء الحقلين 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().
تحتوي الإشعارات أيضًا على سمة رسالة registrationId تحتوي على
معرّف التسجيل الذي أدّى إلى ظهور الإشعار، ويمكن استخدامه
مع
registrations.delete()
لإلغاء التسجيل من الإشعارات.
تاريخ التعديل الأخير: 2025-05-26 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-05-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Push notifications in the Classroom API\n\nYou can use the methods on the\n[`Registrations`](/workspace/classroom/reference/rest/v1/registrations)\ncollection to receive notifications when data changes in Classroom.\n\nThis article provides a conceptual overview along with simple instructions on\nhow to start receiving push notifications.\n\nOverview of Classroom push notifications\n----------------------------------------\n\nThe Classroom API push notifications feature allows applications using the\nClassroom API to subscribe for notifications when data changes in Classroom.\nNotifications are delivered to a [Cloud\nPub/Sub](https://cloud.google.com/pubsub) topic, usually within a few minutes of\nthe change.\n\nTo receive push notifications, you need to [set up a Cloud Pub/Sub\ntopic](#topic-setup) and provide that topic's name when you create a\n**registration** for the appropriate **feed** of notifications.\n\nBelow are definitions of key concepts used in this documentation:\n\n- A **destination** is a place where notifications are sent.\n- A **feed** is a type of notifications that a third party application can subscribe to. For example, \"roster changes for course 1234\".\n- A **registration** is an instruction to the Classroom API to deliver notifications from a particular *feed* to a *destination*.\n\nOnce you create a registration for a feed, that registration's Cloud Pub/Sub\ntopic receives notifications from that feed until it expires. Your registration\nlasts a week, but you can extend it at any point before it expires by making an\nidentical request to `registrations.create()`.\n\nYour Cloud Pub/Sub topic only receives notifications about resources that you\ncan view with the credentials you supply when creating a registration. For\nexample, if the user revokes permission from your application or is removed as a\nteacher, notifications are no longer delivered.\n\n### Types of feeds\n\nThe Classroom API currently offers three types of feed:\n\n- Each domain has a **roster changes for domain** feed, which exposes notifications when students and teachers join and leave courses in that domain.\n- Each course has a **roster changes for course** feed, which exposes notifications when students and teachers join and leave courses in that course.\n- Each course has a **course work changes for course** feed, which exposes notifications when any course work or student submission objects are created or modified in that course.\n\nSetting up a Cloud Pub/Sub topic\n--------------------------------\n\nNotifications are delivered to Cloud Pub/Sub topics. From Cloud Pub/Sub, you can\nreceive notifications on a webhook, or by polling a subscription endpoint.\n\nTo set up a Cloud Pub/Sub topic, you need to do the following:\n\n1. Make sure you fulfill the [Cloud Pub/Sub\n Prerequisites](https://cloud.google.com/pubsub/prereqs).\n2. [Set up a Cloud Pub/Sub client](https://cloud.google.com/pubsub/configure).\n3. Review the [Cloud Pub/Sub pricing](https://cloud.google.com/pubsub/pricing), and enable billing for your Developer Console project.\n4. Create a Cloud Pub/Sub topic [in the Developer\n Console](https://cloud.google.com/pubsub/docs/quickstart-console#create_a_topic)\n (easiest), [via the command line\n tool](https://cloud.google.com/pubsub/docs/quickstart-cli#use_the_gcloud_command-line_tool)\n (for simple programmatic use) or using the [Cloud Pub/Sub\n API](https://cloud.google.com/pubsub/docs/quickstart-client-libraries#create_a_topic_and_a_subscription).\n Note that Cloud Pub/Sub [only allows a limited number of\n topics](https://cloud.google.com/pubsub/quotas), so using one topic to\n receive all your notifications ensures you do not hit scaling issues if your\n application becomes popular.\n\n5. [Create a Subscription in Cloud\n Pub/Sub](https://cloud.google.com/pubsub/docs/subscriber), to tell Cloud\n Pub/Sub how to deliver your notifications.\n\n6. Finally, before registering for Push Notifications, you need to [grant the\n Push Notifications service account\n (`classroom-notifications@system.gserviceaccount.com`)\n permission](https://cloud.google.com/pubsub/docs/access_control#console) to\n publish to your topic.\n\nNOTE: If you grant the Push Notifications service account permission to publish\nto your Cloud Pub/Sub topic, users who can make requests from your Developer\nConsole project will be able to determine that it exists, and register for\nnotifications to it. Many applications store OAuth Client IDs on the client\nside, so end-users might be able to make requests from your Developer Console\nproject. If this applies to you, and you are concerned about end-users sending\nunwanted notifications to your Cloud Pub/Sub topic or knowing the names of Cloud\nPub/Sub topics that you use for push notifications, you should consider\nregistering for push notifications from a different Developer Console project.\n\nRegister your application for notifications\n-------------------------------------------\n\nOnce you have a topic that the Classroom API push notifications service account\ncan publish to, you can register for notifications, using the\n[`registrations.create()`](/workspace/classroom/reference/rest/v1/registrations/create)\nmethod. The `registrations.create()` method validates that the provided Cloud\nPub/Sub topic can be reached by the push notifications service account. The\nmethod fails if the push notifications service account cannot reach the topic;\nfor example, if the topic does not exist or you have not granted it publish\npermission on that topic.\n\n### Authorization\n\nLike all calls to the Classroom API, calls to `registrations.create()` [must be\nauthorized](/workspace/classroom/guides/auth) with an authorization token. This\nauthentication token must include the Push Notifications scope\n(`https://www.googleapis.com/auth/classroom.push-notifications`) and whatever\nscopes are required to view the data about which notifications are being sent.\n\n- For roster change feeds, this means the Rosters scope or (ideally) its read-only variant (`https://www.googleapis.com/auth/classroom.rosters.readonly` or `https://www.googleapis.com/auth/classroom.rosters`).\n- For course work change feeds, this means the \"students\" versions of the course work scope or (ideally) its read-only variant (`https://www.googleapis.com/auth/classroom.coursework.students.readonly` or `https://www.googleapis.com/auth/classroom.coursework.students`).\n\nFor notifications to be delivered, the application must retain an OAuth grant\nfrom the authorized user with the required scopes. If the user disconnects the\napplication, notifications cease. Note that currently, domain-wide delegation of\nauthority is not supported for this purpose. If you attempt to register for\nnotifications using only domain-wide delegated authority, you will receive a\n`@MissingGrant` error.\n\nReceiving notifications\n-----------------------\n\nNotifications are encoded with JSON, and contain:\n\n- The name of the collection containing the resource that changed. For notifications about roster changes, this is either `courses.students` or `courses.teachers`. For course work changes, this is either `courses.courseWork` or `courses.courseWork.studentSubmissions`.\n- Identifiers for the resource that changed, in a map. This map is designed to match the arguments to the `get` method of the appropriate resource. For notifications about roster changes, the `courseId` and `userId` fields will be populated, and can be sent unmodified to [courses.students.get()](/workspace/classroom/reference/rest/v1/courses.students/get) or [courses.teachers.get()](/workspace/classroom/reference/rest/v1/courses.teachers/get). Similarly, changes to the courses.courseWork collection will have `courseId` and `id` fields that can be sent unmodified to [courses.courseWork.get()](/workspace/classroom/reference/rest/v1/courses.courseWork/get) and changes to the courses.courseWork.studentSubmissions collection will have `courseId`, `courseWorkId`, and `id` fields that can be sent unmodified to [courses.courseWork.studentSubmissions.get()](/workspace/classroom/reference/rest/v1/courses.courseWork.studentSubmissions/get).\n\nThe following code snippet demonstrates a sample notification: \n\n {\n \"collection\": \"courses.students\",\n \"eventType\": \"CREATED\",\n \"resourceId\": {\n \"courseId\": \"12345\",\n \"userId\": \"45678\"\n }\n }\n\nNotifications also have a `registrationId` message attribute, containing the\nidentifier for the registration that caused the notification, which can be used\nwith\n[`registrations.delete()`](/workspace/classroom/reference/rest/v1/registrations/delete)\nto unregister from notifications."]]
