इस दस्तावेज़ में बताया गया है कि क्लाइंट को कम कनेक्शन देने के लिए, एपीआई कॉल को एक साथ कैसे बैच में भेजा जाए. बैच बनाने की सुविधा से किसी ऐप्लिकेशन की क्षमता बेहतर हो सकती है. ऐसा करने के लिए, नेटवर्क राउंड ट्रिप को कम किया जा सकता है और क्षमता को बढ़ाया जा सकता है.
खास जानकारी
आपका क्लाइंट हर कनेक्शन, ओवरहेड की एक तय रकम से नतीजे देता है. Google Docs API, एक साथ कई अनुरोधों को प्रोसेस करने की सुविधा देता है. इससे, आपके क्लाइंट को एक ही बैच में कई अनुरोध करने की सुविधा मिल जाती है. हर ऑब्जेक्ट, एक ही तरह के अनुरोध के बारे में बताता है. एक साथ कई अनुरोध करने का अनुरोध करने पर, कई सब-अनुरोधों को सर्वर पर किए गए एक कॉल में जोड़कर परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. ऐसा करके, एक ही जवाब को वापस पाया जा सकता है.
हम उपयोगकर्ताओं को सलाह देते हैं कि वे कई अनुरोधों को हमेशा एक साथ इकट्ठा करें. यहां उन स्थितियों के कुछ उदाहरण दिए गए हैं जिनमें एक साथ कई बैच बनाने की सुविधा इस्तेमाल की जा सकती है:
- आपने अभी-अभी एपीआई का इस्तेमाल करना शुरू किया है और आपके पास अपलोड करने के लिए बहुत सारा डेटा है.
- आपको एक से ज़्यादा ऑब्जेक्ट के मेटाडेटा या प्रॉपर्टी को अपडेट करना होगा, जैसे कि फ़ॉर्मैटिंग.
- आपको कई ऑब्जेक्ट मिटाने होंगे.
सीमाएं, अनुमति देना, और डिपेंडेंसी से जुड़ी ज़रूरी बातें
बैच अपडेट करते समय ध्यान रखने लायक अन्य आइटम की सूची यहां दी गई है:
- बैच में किए जाने वाले हर अनुरोध को, इस्तेमाल की सीमा के लिए एक एपीआई अनुरोध के तौर पर गिना जाता है. इसमें सभी सब-अनुरोध भी शामिल होते हैं.
- बैच अनुरोध की एक बार पुष्टि की जाती है. पुष्टि करने का यह एक तरीका, अनुरोध में शामिल सभी बैच अपडेट ऑब्जेक्ट पर लागू होता है.
- सर्वर सब-अनुरोधों को उसी क्रम में प्रोसेस करता है जिस क्रम में वे बैच रिक्वेस्ट में दिखते हैं. बाद के सब-अनुरोध, पहले किए गए सब-अनुरोधों के दौरान की गई कार्रवाई पर निर्भर हो सकते हैं. उदाहरण के लिए, एक ही बैच में अनुरोध करने पर, उपयोगकर्ता किसी मौजूदा दस्तावेज़ में टेक्स्ट डालकर उसे स्टाइल कर सकते हैं.
बैच की जानकारी
एक बैच में अनुरोध में, batchUpdate
तरीके का एक कॉल
शामिल होता है. इसमें कई सब-रिक्वेस्ट के साथ-साथ, किसी दस्तावेज़ को जोड़ना और फ़ॉर्मैट करना भी शामिल होता है.
हर अनुरोध को लागू किए जाने से पहले उसकी पुष्टि की जाती है. बैच अपडेट के सभी सब-अनुरोध अपने-आप लागू होते हैं. इसका मतलब है कि अगर कोई अनुरोध मान्य नहीं है, तो पूरा अपडेट पूरा नहीं हो पाएगा और कोई भी (संभावित रूप से निर्भर) बदलाव लागू नहीं किए जाएंगे.
कुछ अनुरोध, लागू किए गए अनुरोधों के बारे में जानकारी के साथ जवाब देते हैं. उदाहरण के लिए, ऑब्जेक्ट जोड़ने के सभी बैच अपडेट के अनुरोधों पर जवाब मिलता है, ताकि जोड़े गए नए ऑब्जेक्ट का मेटाडेटा ऐक्सेस किया जा सके. जैसे, आईडी या टाइटल.
इस तरीके से, कई सब-अनुरोधों के साथ एक ही एपीआई बैच अपडेट करने के अनुरोध का इस्तेमाल करके, पूरा Google दस्तावेज़ बनाया जा सकता है.
बैच रिक्वेस्ट का फ़ॉर्मैट
अनुरोध एक JSON अनुरोध होता है जिसमें एक से ज़्यादा, नेस्ट किए गए ऐसे सब-अनुरोध शामिल होते हैं जिनके लिए एक ज़रूरी प्रॉपर्टी होती है: requests
. अलग-अलग अनुरोधों को
अलग-अलग कैटगरी में तैयार किया जाता है. हर अनुरोध,
अनुरोध ऑब्जेक्ट को दिखाने और उसकी प्रॉपर्टी को शामिल करने के लिए, JSON का इस्तेमाल करता है.
बैच रिस्पॉन्स का फ़ॉर्मैट
बैच रिक्वेस्ट का response फ़ॉर्मैट, अनुरोध के फ़ॉर्मैट जैसा ही होता है. सर्वर के रिस्पॉन्स में एक रिस्पॉन्स ऑब्जेक्ट का पूरा जवाब शामिल होता है.
JSON के मुख्य ऑब्जेक्ट की प्रॉपर्टी का नाम replies
है. जवाबों को
कैटगरी में दिखाया जाता है. हर अनुरोध के लिए, हर अनुरोध के इंडेक्स क्रम का इस्तेमाल करके, संबंधित अनुरोध
को लिया जाता है. कुछ अनुरोधों का
कोई जवाब नहीं मिलता और उस अरे इंडेक्स में कोई जवाब मौजूद नहीं होता.
उदाहरण
नीचे दिया गया कोड सैंपल, Docs API की मदद से एक साथ कई बैच बनाने का तरीका दिखाता है.
अनुरोध
बैच रिक्वेस्ट के इस उदाहरण में, ये काम करने का तरीका बताया गया है:
InsertTextRequest
का इस्तेमाल करके, किसी मौजूदा दस्तावेज़ की शुरुआत में,1
के इंडेक्सlocation
के साथ "नमस्ते वर्ल्ड" टेक्स्ट डालें.UpdateTextStyleRequest
का इस्तेमाल करके, "नमस्ते" शब्द को अपडेट करें.startIndex
औरendIndex
, सेगमेंट में फ़ॉर्मैट किए गए टेक्स्ट काrange
तय करते हैं.textStyle
का इस्तेमाल करके, सिर्फ़ "नमस्ते" शब्द के लिए, फ़ॉन्ट स्टाइल को बोल्ड और रंग को नीला करें.WriteControl
फ़ील्ड का इस्तेमाल करके, यह कंट्रोल किया जा सकता है कि लिखने के अनुरोधों को कैसे एक्ज़ीक्यूट किया जाए. ज़्यादा जानकारी के लिए, WriteControl के साथ राज्य को एक जैसा बनाने का तरीका देखें.
{ "requests":[ { "insertText":{ "location":{ "index":1 }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
REQUIRED_REVISION_ID की जगह उस दस्तावेज़ का रिविज़न आईडी डालें जिस पर लिखने का अनुरोध किया गया है.
जवाब
बैच रिक्वेस्ट के इस उदाहरण में, यह जानकारी दिखाई गई है कि बैच में हर सब-अनुरोध को कैसे लागू किया गया है. InsertTextRequest
या UpdateTextStyleRequest
में से किसी का भी रिस्पॉन्स में कोई जवाब नहीं होता. इसलिए, [0] और [1] कैटगरी की इंडेक्स वैल्यू में खाली कर्ली ब्रैकेट होते हैं. एक साथ कई अनुरोध करने पर, WriteControl
ऑब्जेक्ट दिखता है.
इससे यह पता चलता है कि अनुरोध कैसे एक्ज़ीक्यूट किए गए.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }