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

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

इस लेख में, पुश नोटिफ़िकेशन पाने के तरीकों के बारे में खास जानकारी दी गई है. साथ ही, इन आसान तरीकों के बारे में भी बताया गया है.

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

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

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

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

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

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

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

  6. आखिर में, पुश नोटिफ़िकेशन के लिए रजिस्टर करने से पहले, आपको अपने विषय पर पब्लिश करने के लिए, पुश नोटिफ़िकेशन सेवा खाते (classroom-notifications@system.gserviceaccount.com) को अनुमति देनी होगी.

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

सूचनाओं के लिए अपना ऐप्लिकेशन रजिस्टर करें

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

अनुमति देना

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 फ़ील्ड में, बिना किसी बदलाव के भेजा जा सकता है.courseIdidcourses.courseWork.get()courseWorkIdcourses.courseWork.studentSubmissions.get()

यह कोड स्निपेट एक सैंपल सूचना दिखाता है:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

सूचनाओं में registrationId मैसेज एट्रिब्यूट भी होता है. इसमें सूचना की वजह से हुए रजिस्ट्रेशन का आइडेंटिफ़ायर होता है. सूचनाओं की मदद से, रजिस्ट्रेशन रद्द करने के लिए registrations.delete() के साथ इसका इस्तेमाल किया जा सकता है.