कदम-दर-कदम निर्देश

इस सिलसिलेवार गाइड में, Classroom के काम करने वाले ऐड-ऑन के सभी ज़रूरी हिस्सों के बारे में बताया गया है. गाइड के हर चरण में, खास कॉन्सेप्ट के बारे में बताया गया है. साथ ही, उन्हें किसी एक वेब ऐप्लिकेशन में लागू करने का तरीका भी बताया गया है. इसका मकसद, काम करने वाला ऐड-ऑन सेट अप करने, उसे कॉन्फ़िगर करने, और लॉन्च करने में आपकी मदद करना है.

आपके ऐड-ऑन को Google Cloud प्रोजेक्ट के साथ इंटरैक्ट करना होगा. अगर आपको Google Cloud के बारे में जानकारी नहीं है, तो हमारा सुझाव है कि आप शुरू करने के लिए गाइड पढ़ें. क्रेडेंशियल, एपीआई ऐक्सेस, और Google Workspace Marketplace SDK को Google Cloud console में मैनेज किया जाता है. Marketplace SDK के बारे में ज़्यादा जानकारी के लिए, Google Workspace Marketplace लिस्टिंग गाइड वाला पेज देखें.

इस गाइड में इन विषयों के बारे में बताया गया है:

  • Classroom में iframe में दिखाने के लिए, Google Cloud का इस्तेमाल करके पेज बनाना.
  • Google के सिंगल साइन-ऑन (एसएसओ) की सुविधा जोड़ना और उपयोगकर्ताओं को साइन इन करने की अनुमति देना.
  • अपने ऐड-ऑन को किसी असाइनमेंट से अटैच करने के लिए, एपीआई कॉल करना.
  • ऐड-ऑन सबमिट करने की ज़रूरी शर्तें और ज़रूरी सुविधाओं के बारे में जानकारी देना.

इस गाइड में यह मानकर चला जा रहा है कि आपको प्रोग्रामिंग और वेब डेवलपमेंट के बुनियादी कॉन्सेप्ट के बारे में जानकारी है. हमारा सुझाव है कि सिलसिलेवार गाइड को पढ़ने से पहले, प्रोजेक्ट कॉन्फ़िगरेशन गाइड पढ़ें. इस पेज पर, कॉन्फ़िगरेशन से जुड़ी अहम जानकारी दी गई है. यह जानकारी, सिलसिलेवार गाइड में पूरी तरह से शामिल नहीं है.

लागू करने का उदाहरण

रेफ़रंस के तौर पर पूरा उदाहरण Python में उपलब्ध है. Java और Node.js में भी, लागू करने के कुछ उदाहरण उपलब्ध हैं. ये उदाहरण, अगले पेजों पर दिए गए कोड के सोर्स हैं.

डाउनलोड करने की जगह

Python और Java के उदाहरण, GitHub रिपॉज़िटरी में उपलब्ध हैं:

Node.js का सैंपल, zip फ़ाइल के तौर पर डाउनलोड किया जा सकता है:

ज़रूरी शर्तें

ऐड-ऑन के नए प्रोजेक्ट को तैयार करने के लिए, यहां दिए गए सेक्शन देखें.

एचटीटीपीएस सर्टिफ़िकेट

आपके पास अपने ऐप्लिकेशन को किसी भी डेवलपमेंट एनवायरमेंट पर होस्ट करने का विकल्प होता है. हालांकि, Classroom का ऐड-ऑन सिर्फ़ https:// के ज़रिए उपलब्ध होता है. इसलिए, अपने ऐप्लिकेशन को डिप्लॉय करने या ऐड-ऑन के iframe में उसकी टेस्टिंग करने के लिए, आपको एसएसएल एन्क्रिप्ट (सुरक्षित) वाला सर्वर चाहिए.

एसएसएल सर्टिफ़िकेट के साथ localhost का इस्तेमाल किया जा सकता है. अगर आपको लोकल डेवलपमेंट के लिए कोई सर्टिफ़िकेट बनाना है, तो mkcert का इस्तेमाल करें.

Google Cloud प्रोजेक्ट

इन उदाहरणों के साथ इस्तेमाल करने के लिए, आपको Google Cloud प्रोजेक्ट को कॉन्फ़िगर करना होगा. शुरू करने के लिए ज़रूरी चरणों की खास जानकारी पाने के लिए, Google Cloud प्रोजेक्ट बनाने की गाइड देखें. पहली सिलसिलेवार गाइड में, Google Cloud प्रोजेक्ट सेट अप करें सेक्शन में, कॉन्फ़िगरेशन से जुड़ी उन खास कार्रवाइयों के बारे में भी बताया गया है जो आपको करनी होंगी.

पूरा होने के बाद, OAuth 2.0 क्लाइंट आईडी को JSON फ़ाइल के तौर पर डाउनलोड करें. आपको इस क्रेडेंशियल फ़ाइल को, अनज़िप की गई उदाहरण डायरेक्ट्री में जोड़ना होगा. खास जगहों के बारे में जानने के लिए, फ़ाइलें समझना देखें.

OAuth क्रेडेंशियल

OAuth के नए क्रेडेंशियल बनाने के लिए, यह तरीका अपनाएं:

  • Google Cloud के क्रेडेंशियल वाले पेज पर जाएं. पक्का करें कि स्क्रीन पर सबसे ऊपर, सही प्रोजेक्ट चुना गया हो.
  • क्रेडेंशियल बनाएं पर क्लिक करें और ड्रॉप-डाउन में से OAuth क्लाइंट आईडी चुनें.
  • अगले पेज पर:
    • ऐप्लिकेशन का टाइप को वेब ऐप्लिकेशन पर सेट करें.
    • अनुमति वाले रीडायरेक्ट यूआरआई में जाकर, यूआरआई जोड़ें पर क्लिक करें. अपने ऐप्लिकेशन के लिए, कॉलबैक रूट का पूरा पाथ जोड़ें. उदाहरण के लिए, https://my.domain.com/auth-callback या https://localhost:5000/callback. इस सिलसिलेवार गाइड में, इस रूट को बाद में बनाया और मैनेज किया जाएगा. आपके पास ऐसे रूट को कभी भी जोड़ने या उनमें बदलाव करने का विकल्प होता है.
    • बनाएं पर क्लिक करें.
  • इसके बाद, आपको नए क्रेडेंशियल के साथ एक डायलॉग दिखेगा. JSON डाउनलोड करें विकल्प चुनें. डाउनलोड की गई JSON फ़ाइल को अपने सर्वर डायरेक्ट्री में कॉपी करें.

भाषा के हिसाब से ज़रूरी शर्तें

ज़रूरी शर्तों की सबसे नई सूची के लिए, हर रिपॉज़िटरी में मौजूद README फ़ाइल देखें.

Python

हमारे Python के उदाहरण में, Flask फ़्रेमवर्क का इस्तेमाल किया गया है. दिए गए लिंक से, सोर्स कोड डाउनलोड किया जा सकता है.

ज़रूरत पड़ने पर, Python 3.7 या इसके बाद का वर्शन इंस्टॉल करें और पक्का करें कि pip उपलब्ध हो.

python3 -m ensurepip --upgrade

हमारा सुझाव है कि आप Python का नया वर्चुअल एनवायरमेंट सेट अप और चालू करें.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

डाउनलोड किए गए उदाहरणों में, सिलसिलेवार गाइड की हर सबडायरेक्ट्री में requirements.txt मौजूद है. pip का इस्तेमाल करके, ज़रूरी लाइब्रेरी को तुरंत इंस्टॉल किया जा सकता है. पहली सिलसिलेवार गाइड के लिए ज़रूरी लाइब्रेरी इंस्टॉल करने के लिए, इन कमांड का इस्तेमाल करें.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

हमारे Node.js के उदाहरण में, Express फ़्रेमवर्क का इस्तेमाल किया गया है. दिए गए लिंक से, सोर्स कोड डाउनलोड किया जा सकता है.

इस उदाहरण के लिए, Node.js v16.13 या इसके बाद का वर्शन ज़रूरी है.

npm का इस्तेमाल करके, ज़रूरी नोड मॉड्यूल इंस्टॉल करें.

npm install

Java

हमारे Java के उदाहरण में, Spring Boot फ़्रेमवर्क का इस्तेमाल किया गया है. दिए गए लिंक से, सोर्स कोड डाउनलोड किया जा सकता है.

अगर आपके कंप्यूटर पर Java 11 या इसके बाद का वर्शन इंस्टॉल नहीं है, तो उसे इंस्टॉल करें.

Spring Boot ऐप्लिकेशन, Gradle या Maven का इस्तेमाल करके बिल्ड को मैनेज कर सकते हैं और डिपेंडेंसी मैनेज कर सकते हैं. इस उदाहरण में, Maven रैपर शामिल है. इससे, Maven को इंस्टॉल किए बिना ही, बिल्ड को सही तरीके से पूरा किया जा सकता है.

जिस डायरेक्ट्री में आपने प्रोजेक्ट डाउनलोड या क्लोन किया है, उसमें ये कमांड चलाएं. इससे पक्का होगा कि आपके पास प्रोजेक्ट चलाने के लिए ज़रूरी शर्तें पूरी हों.

java --version
./mvnw --version

या Windows पर:

java -version
mvnw.cmd --version

फ़ाइलें समझना

यहां दिए गए सेक्शन में, उदाहरण डायरेक्ट्री के लेआउट के बारे में बताया गया है.

डायरेक्ट्री के नाम

हर रिपॉज़िटरी में कई डायरेक्ट्री होती हैं. इनके नाम किसी संख्या से शुरू होते हैं. जैसे, /01-basic-app/. ये संख्याएं, सिलसिलेवार गाइड के खास चरणों से जुड़ी होती हैं. हर डायरेक्ट्री में, पूरी तरह से काम करने वाला वेब ऐप्लिकेशन होता है. इसमें, सिलसिलेवार गाइड में बताई गई सुविधाएं लागू की जाती हैं. उदाहरण के लिए, /01-basic-app/ डायरेक्ट्री में, ऐड-ऑन बनाएं सिलसिलेवार गाइड के लिए, लागू करने का फ़ाइनल तरीका शामिल है.

डायरेक्ट्री का कॉन्टेंट

डायरेक्ट्री का कॉन्टेंट, लागू करने की भाषा के हिसाब से अलग-अलग होता है:

Python

  • डायरेक्ट्री रूट में ये फ़ाइलें शामिल हैं:

    • main.py - Python ऐप्लिकेशन का एंट्री पॉइंट. इस फ़ाइल में, वह सर्वर कॉन्फ़िगरेशन तय करें जिसका आपको इस्तेमाल करना है. इसके बाद, सर्वर शुरू करने के लिए इसे चलाएं.
    • requirements.txt - वेब ऐप्लिकेशन चलाने के लिए ज़रूरी Python मॉड्यूल. इन्हें pip install -r requirements.txt का इस्तेमाल करके, अपने-आप इंस्टॉल किया जा सकता है.

    • client_secret.json - Google Cloud से डाउनलोड की गई क्लाइंट सीक्रेट फ़ाइल. ध्यान दें कि यह उदाहरण संग्रह में शामिल नहीं है. आपको डाउनलोड की गई क्रेडेंशियल फ़ाइल का नाम बदलना होगा और उसे हर डायरेक्ट्री रूट में कॉपी करना होगा.

  • config.py - Flask सर्वर के लिए कॉन्फ़िगरेशन के विकल्प.

  • webapp डायरेक्ट्री में, वेब ऐप्लिकेशन का कॉन्टेंट शामिल होता है. इसमें ये शामिल हैं:

  • अलग-अलग पेजों के लिए Jinja टेंप्लेट वाली /templates/ डायरेक्ट्री.

  • इमेज, सीएसएस, और सहायक JavaScript फ़ाइलों वाली /static/ डायरेक्ट्री.

  • routes.py - वेब ऐप्लिकेशन के रूट के लिए हैंडलर के तरीके.

  • __init__.py - webapp मॉड्यूल के लिए इनिशियलाइज़र. यह इनिशियलाइज़र, Flask सर्वर शुरू करता है और config.py में सेट किए गए कॉन्फ़िगरेशन के विकल्प लोड करता है.

  • किसी खास सिलसिलेवार गाइड के चरण के लिए ज़रूरी अन्य फ़ाइलें.

Node.js

सिलसिलेवार गाइड का हर चरण, <step> सब-फ़ोल्डर में मौजूद होता है. हर चरण में ये शामिल हैं:

  • JavaScript, सीएसएस, और इमेज जैसी स्टैटिक फ़ाइलें, ./<step>/public फ़ोल्डर में मौजूद होती हैं.
  • Express राऊटर, ./<step>/routes फ़ोल्डर में मौजूद होते हैं.
  • एचटीएमएल टेंप्लेट, ./<step>/views फ़ोल्डर में मौजूद होते हैं.
  • सर्वर ऐप्लिकेशन, ./<step>/app.js होता है.

Java

प्रोजेक्ट डायरेक्ट्री में ये शामिल हैं:

  • src.main डायरेक्ट्री में, सोर्स कोड और कॉन्फ़िगरेशन शामिल होता है. इसकी मदद से, ऐप्लिकेशन को सही तरीके से चलाया जा सकता है. इस डायरेक्ट्री में ये शामिल हैं: + java.com.addons.spring डायरेक्ट्री में Application.java और Controller.java फ़ाइलें शामिल हैं. Application.java फ़ाइल, ऐप्लिकेशन सर्वर को चलाने के लिए होती है. वहीं, Controller.java फ़ाइल, एंडपॉइंट लॉजिक को हैंडल करती है. + resources डायरेक्ट्री में, एच101} एचटीएमएल और JavaScript फ़ाइलों वाली templates डायरेक्ट्री शामिल होती है. इसमें application.properties फ़ाइल भी शामिल होती है. इसमें, सर्वर चलाने के लिए पोर्ट, कीस्टोर फ़ाइल का पाथ, और templates डायरेक्ट्री का पाथ तय किया जाता है. इस उदाहरण में, कीस्टोर फ़ाइल resources डायरेक्ट्री में शामिल है. आपके पास इसे कहीं भी सेव करने का विकल्प होता है. हालांकि, पक्का करें कि आपने application.properties फ़ाइल को पाथ के हिसाब से अपडेट कर दिया हो.
    • pom.xml में, प्रोजेक्ट को बिल्ड करने और ज़रूरी डिपेंडेंसी तय करने के लिए ज़रूरी जानकारी शामिल होती है.
    • .gitignore में, उन फ़ाइल के नाम शामिल होते हैं जिन्हें git पर अपलोड नहीं किया जाना चाहिए. पक्का करें कि आपने इसमें अपने कीस्टोर का पाथ जोड़ा हो .gitignore. दिए गए उदाहरण में, यह secrets/*.p12 है. कीस्टोर के मकसद के बारे में, नीचे दिए गए सेक्शन में बताया गया है. सिलसिलेवार गाइड के दूसरे और इसके बाद के चरणों के लिए, आपको अपनी client_secret.json फ़ाइल का पाथ भी शामिल करना चाहिए. इससे पक्का होगा कि आपने रिमोट रिपॉज़िटरी में अपने सीक्रेट शामिल नहीं किए हैं. सिलसिलेवार गाइड के तीसरे और इसके बाद के चरणों के लिए, आपको H2 डेटाबेस फ़ाइल और फ़ाइल डेटास्टोर फ़ैक्ट्री का पाथ जोड़ना चाहिए. इन डेटा स्टोर को सेट अप करने के बारे में ज़्यादा जानकारी, बार-बार आने वाले लोगों को हैंडल करने के बारे में तीसरी सिलसिलेवार गाइड में मिल सकती है.
    • mvnw और mvnw.cmd, Unix और Windows के लिए Maven रैपर एक्ज़ीक्यूटेबल हैं. उदाहरण के लिए, Unix पर ./mvnw --version चलाने पर, Apache Maven का वर्शन दिखता है. इसके अलावा, अन्य जानकारी भी दिखती है.
    • .mvn डायरेक्ट्री में, Maven रैपर के लिए कॉन्फ़िगरेशन शामिल होता है.

सैंपल सर्वर चलाना

आपको अपने सर्वर को लॉन्च करना होगा, ताकि उसकी टेस्टिंग की जा सके. अपनी चुनी हुई भाषा में, उदाहरण के तौर पर दिए गए सर्वर को चलाने के लिए, यह तरीका अपनाएं:

Python

OAuth क्रेडेंशियल

पहले बताए गए तरीके के मुताबिक, OAuth क्रेडेंशियल बनाएं और डाउनलोड करें. JSON फ़ाइल को रूट डायरेक्ट्री में, अपने ऐप्लिकेशन के सर्वर लॉन्च फ़ाइल के साथ रखें.

सर्वर को कॉन्फ़िगर करना

वेब सर्वर चलाने के लिए, आपके पास कई विकल्प हैं. अपनी Python फ़ाइल के आखिर में, इनमें से कोई एक विकल्प जोड़ें:

  1. सुरक्षित नहीं किया गया localhost. ध्यान दें कि यह सिर्फ़ ब्राउज़र विंडो में सीधे तौर पर टेस्टिंग के लिए सही है. सुरक्षित नहीं किए गए डोमेन को, Classroom के ऐड-ऑन iframe में लोड नहीं किया जा सकता.

    if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)

  2. सुरक्षित किया गया localhost. ssl_context आर्ग्युमेंट के लिए, आपको एसएसएल कुंजी फ़ाइलों का टपल तय करना होगा.

    if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

  3. Gunicorn सर्वर. यह प्रोडक्शन के लिए तैयार सर्वर या क्लाउड डिप्लॉयमेंट के लिए सही है. हमारा सुझाव है कि इस लॉन्च विकल्प के साथ इस्तेमाल करने के लिए, PORT एनवायरमेंट वैरिएबल सेट करें.

    if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

सर्वर लॉन्च करना

सर्वर लॉन्च करने के लिए, अपना Python ऐप्लिकेशन चलाएं. इसे पिछले चरण में कॉन्फ़िगर किया गया था. 

python main.py

पक्का करें कि आपका वेब ऐप्लिकेशन सही तरीके से चल रहा है. इसके लिए, ब्राउज़र में अपना वेब ऐप्लिकेशन देखने के लिए, दिखने वाले यूआरएल पर क्लिक करें.

Node.js

सर्वर को कॉन्फ़िगर करना

सर्वर को एचटीटीपीएस पर चलाने के लिए, आपको एक सेल्फ़-सर्टिफ़िकेट बनाना होगा. इसका इस्तेमाल, ऐप्लिकेशन को एचटीटीपीएस पर चलाने के लिए किया जाता है. इन क्रेडेंशियल को रिपॉज़िटरी के रूट फ़ोल्डर में, sslcert/cert.pem और sslcert/key.pem के तौर पर सेव किया जाना चाहिए. हो सकता है कि आपको इन कुंजियों को अपने ओएस की की चेन में जोड़ना पड़े, ताकि आपका ब्राउज़र इन्हें स्वीकार कर सके.

पक्का करें कि *.pem आपकी .gitignore फ़ाइल में मौजूद हो, क्योंकि आपको फ़ाइल को git पर कमिट नहीं करना है.

सर्वर लॉन्च करना

आपके पास इस कमांड का इस्तेमाल करके, ऐप्लिकेशन को चलाने का विकल्प होता है. इसमें step01 को उस सही चरण से बदलें जिसे आपको सर्वर के तौर पर चलाना है. उदाहरण के लिए, 01-basic-app के लिए step01 और 02-sign-in के लिए step02.

npm run step01

या

npm run step02

इससे वेब सर्वर, https://localhost:5000 पर लॉन्च होता है.

आपके पास टर्मिनल में Control + C दबाकर, सर्वर को बंद करने का विकल्प होता है.

Java

सर्वर को कॉन्फ़िगर करना

सर्वर को एचटीटीपीएस पर चलाने के लिए, आपको एक सेल्फ़-सर्टिफ़िकेट बनाना होगा. इसका इस्तेमाल, ऐप्लिकेशन को एचटीटीपीएस पर चलाने के लिए किया जाता है.

लोकल डेवलपमेंट के लिए, mkcert का इस्तेमाल करें. mkcert इंस्टॉल करने के बाद, इन कमांड से स्थानीय तौर पर सेव किया गया सर्टिफ़िकेट जनरेट होता है. इसका इस्तेमाल, एचटीटीपीएस पर चलाने के लिए किया जाता है.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

इस उदाहरण में, कीस्टोर फ़ाइल, resources डायरेक्ट्री में शामिल है. आपके पास इसे कहीं भी सेव करने का विकल्प होता है. हालांकि, पक्का करें कि आपने application.properties फ़ाइल को पाथ के हिसाब से अपडेट कर दिया हो. डोमेन का नाम, वह डोमेन होता है जिस पर प्रोजेक्ट चलाया जाता है. उदाहरण के लिए, localhost.

पक्का करें कि *.p12 आपकी .gitignore फ़ाइल में मौजूद हो, क्योंकि आपको फ़ाइल को git पर कमिट नहीं करना है.

सर्वर लॉन्च करना

Application.java फ़ाइल में, main तरीका चलाकर सर्वर लॉन्च करें. उदाहरण के लिए, IntelliJ में, Application.java > Run 'Application' डायरेक्ट्री में, src/main/java/com/addons/spring पर राइट-क्लिक किया जा सकता है. इसके अलावा, main(String[] args) तरीके के सिग्नेचर के बाईं ओर मौजूद हरे ऐरो पर क्लिक करने के लिए, Application.java फ़ाइल खोली जा सकती है. इसके अलावा, टर्मिनल विंडो में प्रोजेक्ट चलाया जा सकता है:

./mvnw spring-boot:run

या Windows पर:

mvnw.cmd spring-boot:run

इससे सर्वर, https://localhost:5000 पर या application.properties में तय किए गए पोर्ट पर लॉन्च होता है.