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 में तीन तरह के फ़ीड होते हैं:

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

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

ध्यान दें: अगर आपने पुश नोटिफ़िकेशन सेवा खाते को अपने 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 तरीके के साथ, आर्ग्युमेंट को मैच करने के लिए डिज़ाइन किया गया है. नामावली में होने वाले बदलावों की सूचना के लिए, courseId और userId फ़ील्ड की जानकारी अपने-आप भर जाएगी. साथ ही, courses.students.get() या courses.teachers.get() में बिना बदलाव के भेजे जा सकते हैं. इसी तरह,course.courseWork कलेक्शन में courseId और id फ़ील्ड शामिल होंगे, जिन्हें courses.courseWork.get() में बिना बदलाव भेजा जा सकता है.idकोर्स.course.work.get() में बदलाव भेजा जा सकता है.id.कोर्स.courseWorkWork.get()courseIdcourseWorkIdcourses.courseWork.studentSubmissions.get()

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

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

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