अनुरोध कैसे काम करते हैं

इस पेज पर, Google Classroom API में अनुरोधों के काम करने के तरीके के बारे में खास जानकारी दी गई है. इसका मकसद उन लोगों की मदद करना है जिन्हें रिसोर्स ओरिएंटेड डिज़ाइन या Google Workspace API के बारे में पहले से जानकारी नहीं है.

कोड के कुछ उदाहरणों के लिए, एपीआई से जुड़ी गाइड देखें. उदाहरण के लिए, कोर्स बनाना और उन्हें मैनेज करना या क्लासवर्क बनाना और उसे मैनेज करना.

संसाधन के हिसाब से डिज़ाइन करना

एपीआई संसाधनों में बताए गए तरीके के मुताबिक, Classroom API, संसाधन-उन्मुख डिज़ाइन पैटर्न का पालन करता है. ज़्यादातर संसाधनों में, स्टैंडर्ड ऑपरेशन के तरीके होते हैं. जैसे, संसाधन के इंस्टेंस बनाना, पढ़ना, अपडेट करना, और मिटाना.

उदाहरण के लिए, एपीआई का इस्तेमाल करके Classroom Course को create(), patch(), get(), list(), और delete() किया जा सकता है.

बनाएं

Course जैसे नए संसाधन बनाने के लिए, उससे जुड़े संसाधन के लिए create() तरीके को कॉल करें.

Create() कॉल के लिए, इनपुट के तौर पर हमेशा संबंधित संसाधन की शुरुआती और ज़रूरी जानकारी की ज़रूरत होती है. उदाहरण के लिए, Course बनाने के लिए, Course रिसोर्स पर create() तरीके को कॉल करें. साथ ही, अनुरोध में name और description के साथ-साथ, room जैसी वैकल्पिक जानकारी दें.

सब-रिसोर्स (कभी-कभी इन्हें चाइल्ड रिसोर्स भी कहा जाता है) के लिए, पैरंट रिसोर्स के आइडेंटिफ़ायर भी ज़रूरी होते हैं. उदाहरण के लिए, Course में CourseWork बनाते समय, यह तय करने के लिए Course id की ज़रूरत होती है कि CourseWork किस Course से जुड़ा है.

Create() तरीके, एपीआई कॉल के जवाब में नई बनाई गई संसाधन का इंस्टेंस दिखाते हैं. आम तौर पर, दिखाए गए रिसॉर्स में सर्वर से जनरेट किए गए अतिरिक्त फ़ील्ड होते हैं. जैसे, रिसॉर्स id या creationTime.

पैच

मौजूदा संसाधनों में बदलाव करने के लिए, उनसे जुड़े संसाधन पर patch() तरीके (जिसे कभी-कभी update() भी कहा जाता है) का इस्तेमाल करें. patch() तरीका, create() तरीके जैसा ही है. हालांकि, इसमें दो मुख्य अंतर हैं. patch() तरीके को कॉल करते समय, आपको ये जानकारी देनी होगी:

1. बदलाव करने के लिए संसाधन का id.
2. फ़ील्ड की सूची को updateMask कहा जाता है. इससे यह तय किया जाता है कि संसाधन के किन फ़ील्ड को अपडेट करना है. अगर फ़ील्ड का डिफ़ॉल्ट सेट मौजूद है या फ़ील्ड का अनुमान लगाया गया है, तो यह विकल्प ज़रूरी नहीं है.

अहम जानकारी: आपको patch() तरीकों के साथ-साथ update() तरीके भी दिख सकते हैं. दोनों ही किसी संसाधन में बदलाव करते हैं, लेकिन इनके व्यवहार में अंतर होता है. Update() किसी संसाधन को पूरी तरह से नए संसाधन से बदल देता है, जबकि patch() सिर्फ़ चुने गए फ़ील्ड को अपडेट करता है. उदाहरण के लिए, courses.update(), मौजूदा Course को पूरी तरह से बदल देता है. वहीं, courses.patch(), ऊपर बताए गए fieldMask का इस्तेमाल करके, Course के सिर्फ़ कुछ फ़ील्ड में बदलाव करता है. आसानी से इस्तेमाल करने के लिए, Google Classroom API में ज़्यादातर patch() का इस्तेमाल किया जाता है. हमारा सुझाव है कि आप आम तौर पर इसी तरीके का इस्तेमाल करें.

Patch() तरीके, एपीआई कॉल के जवाब में अपडेट किए गए संसाधन का पूरा इंस्टेंस दिखाते हैं. इसमें सभी बदलाव शामिल होते हैं.

Get and list

संसाधन वापस पाने के दो तरीके हैं: get() और list().

get() तरीके से, किसी आइडेंटिफ़ायर के ज़रिए किसी संसाधन को वापस पाया जाता है. उदाहरण के लिए, id या alias के आधार पर Course को फ़ेच करना. get() कॉल, पूरे संसाधन को सीधे तौर पर दिखाता है.

list() तरीके से, एक ही तरह के कई संसाधनों को एक ही अनुरोध में वापस पाया जा सकता है. इसके लिए, अलग-अलग संसाधन आइडेंटिफ़ायर की ज़रूरत नहीं होती. अक्सर list() ऑपरेशन, किसी पैरंट रिसॉर्स के सभी सबरिसॉर्स को फ़ेच करता है. उदाहरण के लिए, किसी Course में मौजूद सभी CourseWork को फ़ेच करना. यह कई get() कॉल करने की तुलना में, अनुरोधों को कम करने के लिए फ़ायदेमंद है. साथ ही, यह तब ज़्यादा फ़ायदेमंद होता है, जब आपको उन संसाधनों के id के बारे में पता न हो जिनकी आपको ज़रूरत है.

आम तौर पर, list() तरीकों में संसाधनों की कुछ ज़्यादा से ज़्यादा संख्या होती है, जिन्हें एक कॉल में वापस किया जा सकता है. साथ ही, कॉल में pageSize वैल्यू शामिल करके, कम सीमाएं कॉन्फ़िगर की जा सकती हैं. अगर संसाधनों की संख्या तय सीमा से ज़्यादा है, तो list() तरीके में पेजों का क्रम तय करने की सुविधा काम करती है. नतीजों के हर "पेज" में pageToken शामिल होता है. इसे list() के अगले कॉल में शामिल किया जा सकता है, ताकि संसाधनों का अगला बैच फ़ेच किया जा सके.

मिटाएं

delete() तरीके में, id जैसे रिसॉर्स आइडेंटिफ़ायर को स्वीकार किया जाता है. साथ ही, इससे जुड़े रिसॉर्स को मिटा दिया जाता है. अगर delete() अनुरोध पूरा हो जाता है, तो कोई जवाब नहीं मिलता.

अन्य कार्रवाइयां

Classroom API की मदद से की जा सकने वाली सभी कार्रवाइयां, ऊपर बताई गई स्टैंडर्ड कार्रवाइयों की मदद से नहीं की जा सकतीं. उदाहरण के लिए, CourseWork संसाधन के लिए असाइन किए गए लोगों की जानकारी में बदलाव करना. ऐसे मामलों में, कस्टम तरीके उपलब्ध होते हैं. जैसे, modifyAssignees तरीका. इन तरीकों का व्यवहार अलग-अलग होता है. इसलिए, आपको इनके दस्तावेज़ अलग-अलग देखने चाहिए.