Classroom API में पुश नोटिफ़िकेशन

Classroom में डेटा में बदलाव होने पर सूचनाएं पाने के लिए, Registrations कलेक्शन में दिए गए तरीकों का इस्तेमाल किया जा सकता है.

इस लेख में, पुश नोटिफ़िकेशन पाने की सुविधा के बारे में खास जानकारी दी गई है. साथ ही, पुश नोटिफ़िकेशन पाने की सुविधा शुरू करने के बारे में आसान निर्देश दिए गए हैं.

Classroom के पुश नोटिफ़िकेशन के बारे में खास जानकारी

Classroom API की पुश नोटिफ़िकेशन सुविधा की मदद से, Classroom API का इस्तेमाल करने वाले ऐप्लिकेशन, Classroom में डेटा में बदलाव होने पर सूचनाएं पाने के लिए सदस्यता ले सकते हैं. सूचनाएं, Cloud Pub/Sub विषय पर डिलीवर की जाती हैं. आम तौर पर, बदलाव होने के कुछ मिनटों के अंदर ऐसा होता है.

पुश नोटिफ़िकेशन पाने के लिए, आपको Cloud Pub/Sub विषय सेट अप करना होगा. साथ ही, सूचनाओं के सही फ़ीड के लिए रजिस्ट्रेशन बनाते समय, उस विषय का नाम देना होगा.

इस दस्तावेज़ में इस्तेमाल किए गए मुख्य कॉन्सेप्ट की परिभाषाएं यहां दी गई हैं:

• डेस्टिनेशन वह जगह होती है जहां सूचनाएं भेजी जाती हैं.
• फ़ीड एक तरह की सूचनाएं होती हैं. तीसरे पक्ष का कोई ऐप्लिकेशन इन्हें पाने के लिए सदस्यता ले सकता है. उदाहरण के लिए, "कोर्स 1234 के लिए रोस्टर में बदलाव".
• रजिस्ट्रेशन, Classroom API को दिया गया एक निर्देश होता है. इसके ज़रिए, किसी फ़ीड से सूचनाएं, किसी डेस्टिनेशन पर भेजी जाती हैं.

किसी फ़ीड के लिए रजिस्ट्रेशन बनाने के बाद, उस रजिस्ट्रेशन का Cloud Pub/Sub विषय, उस फ़ीड से सूचनाएं तब तक पाता है, जब तक उसकी समयसीमा खत्म नहीं हो जाती. आपका रजिस्ट्रेशन एक हफ़्ते तक मान्य रहता है. हालांकि, इसकी समयसीमा खत्म होने से पहले, इसे बढ़ाया जा सकता है. इसके लिए, आपको registrations.create() पर जाकर वैसा ही अनुरोध करना होगा.

आपके Cloud Pub/Sub विषय को सिर्फ़ उन संसाधनों के बारे में सूचनाएं मिलती हैं जिन्हें रजिस्ट्रेशन बनाते समय दी गई क्रेडेंशियल की मदद से देखा जा सकता है. उदाहरण के लिए, अगर उपयोगकर्ता आपके ऐप्लिकेशन से अनुमति वापस ले लेता है या उसे शिक्षक की भूमिका से हटा दिया जाता है, तो सूचनाएं नहीं भेजी जाती हैं.

फ़ीड के प्रकार

Classroom API में तीन तरह के फ़ीड होते हैं:

• हर डोमेन में डोमेन के लिए रोस्टर में हुए बदलाव फ़ीड होता है. इससे सूचनाएं मिलती हैं. ये सूचनाएं तब मिलती हैं, जब छात्र-छात्राएं और शिक्षक उस डोमेन में कोर्स में शामिल होते हैं और छोड़ते हैं.
• हर कोर्स के लिए, कोर्स के लिए रोस्टर में बदलाव फ़ीड होता है. इससे छात्र-छात्राओं और शिक्षकों के किसी कोर्स में शामिल होने और उसे छोड़ने पर सूचनाएं मिलती हैं.
• हर कोर्स के लिए, कोर्स के काम में हुए बदलावों की जानकारी फ़ीड होता है. इससे सूचनाएं मिलती हैं. ये सूचनाएं तब मिलती हैं, जब उस कोर्स में कोई कोर्स वर्क या छात्र-छात्रा के सबमिट किए गए ऑब्जेक्ट बनाए जाते हैं या उनमें बदलाव किया जाता है.

ध्यान दें: हमें एक समस्या के बारे में पता है. इस समस्या में, उन कोर्स में किए गए बदलावों के लिए सूचनाएं नहीं भेजी जाती हैं जिनमें कोर्स का मालिक, Google Workspace for Education डोमेन का हिस्सा नहीं है. अगर आपको ऐसे कोर्स पर काम करना है जो Google Workspace for Education डोमेन से नहीं जुड़े हैं, तो ध्यान रखें कि COURSE_ROSTER_CHANGES feedType की सूचनाएं काम नहीं कर सकती हैं.

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. Developer Console में (सबसे आसान तरीका), कमांड लाइन टूल की मदद से (प्रोग्राम के ज़रिए आसानी से इस्तेमाल करने के लिए) या Cloud Pub/Sub API का इस्तेमाल करके, Cloud Pub/Sub विषय बनाएं. ध्यान दें कि Cloud Pub/Sub सिर्फ़ कुछ ही विषयों की अनुमति देता है. इसलिए, सभी सूचनाएं पाने के लिए एक विषय का इस्तेमाल करने से, यह पक्का होता है कि अगर आपका ऐप्लिकेशन लोकप्रिय हो जाता है, तो आपको स्केलिंग से जुड़ी समस्याएं नहीं आएंगी.

5. Cloud Pub/Sub में सदस्यता बनाएं, ताकि Cloud Pub/Sub को यह पता चल सके कि सूचनाएं कैसे डिलीवर करनी हैं.

6. पुश नोटिफ़िकेशन के लिए रजिस्टर करने से पहले, आपको पुश नोटिफ़िकेशन सेवा खाते ([e-mail]) को अपने विषय पर पब्लिश करने की अनुमति देनी होगी.

ध्यान दें: अगर आपने Push Notifications सेवा खाते को Cloud Pub/Sub topic पर पब्लिश करने की अनुमति दी है, तो 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 तरीके से तर्कों का मिलान कर सके. रोस्टर में हुए बदलावों की सूचनाओं के लिए, 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() के साथ किया जा सकता है, ताकि सूचनाएं पाने के लिए किए गए रजिस्ट्रेशन को रद्द किया जा सके.