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

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

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

संसाधन-ओरिएंटेड डिज़ाइन

एपीआई स्ट्रक्चर में बताए गए मुताबिक, 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() तरीके, एपीआई कॉल के जवाब में अपडेट किए गए संसाधन का पूरा इंस्टेंस दिखाते हैं. इसमें सभी बदलाव पूरे हो चुके होते हैं.

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

संसाधनों को वापस पाने के दो तरीके हैं: 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 जैसे कस्टम तरीके उपलब्ध होते हैं. इन तरीकों के काम करने का तरीका अलग-अलग होता है. इसलिए, आपको इनके लिए अलग-अलग दस्तावेज़ देखना चाहिए.