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

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

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

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

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

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

बनाएं

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(), Course में सिर्फ़ चुनिंदा फ़ील्ड में बदलाव करने के लिए, ऊपर बताए गए fieldMask का इस्तेमाल करता है. आसानी से इस्तेमाल करने के लिए, Google Classroom API patch() का इस्तेमाल करता है. हमारा सुझाव है कि आप आम तौर पर इस तरीके का इस्तेमाल करें.

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

पाना और सूची बनाना

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

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

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

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

मिटाएं

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

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

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