बैच अनुरोध

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

खास जानकारी

आपके क्लाइंट के हर कनेक्शन से एक तय ओवरहेड होता है. Google Docs API, एक साथ कई अनुरोध करने की सुविधा देता है, ताकि आपका क्लाइंट एक से ज़्यादा अनुरोध वाले ऑब्जेक्ट डाल सके. इनमें हर अनुरोध के लिए एक ही तरह के अनुरोध के बारे में बताया जाता है. यह अनुरोध एक ही बैच में किया जाता है. एक साथ कई अनुरोध करने की प्रोसेस से, कई सब-अनुरोधों को मिलाकर सर्वर को एक ही कॉल में शामिल किया जा सकता है और परफ़ॉर्मेंस को बेहतर किया जा सकता है. इससे, एक ही जवाब वापस पाया जा सकता है.

हम उपयोगकर्ताओं को सलाह देते हैं कि वे कई अनुरोधों को एक साथ हमेशा बैच बनाएं. यहां उन स्थितियों के कुछ उदाहरण दिए गए हैं जिनमें एक साथ कई अनुरोध भेजने की सुविधा का इस्तेमाल किया जा सकता है:

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

सीमाएं, अनुमति देने, और डिपेंडेंसी के बारे में खास जानकारी

यहां उन अन्य आइटम की सूची दी गई है जिन पर बैच अपडेट करने की सुविधा का इस्तेमाल करते समय ध्यान रखना ज़रूरी है:

  • बैच में किए गए हर अनुरोध को, इस्तेमाल करने की सीमा के लिए एक एपीआई अनुरोध के तौर पर गिना जाता है. इसमें सभी सब-अनुरोध भी शामिल हैं.
  • एक साथ कई अनुरोधों की पुष्टि करने की प्रोसेस एक बार की जाती है. यह एक ही पुष्टि करने की यह प्रोसेस, अनुरोध में शामिल सभी बैच अपडेट ऑब्जेक्ट पर लागू होती है.
  • सर्वर, सब-अनुरोधों को उसी क्रम में प्रोसेस करता है जिस क्रम में वे बैच रिक्वेस्ट में दिखते हैं. बाद के सब-अनुरोध, पहले के सब-अनुरोधों के दौरान की गई कार्रवाइयों पर निर्भर हो सकते हैं. उदाहरण के लिए, एक ही बैच में अनुरोध में, उपयोगकर्ता किसी मौजूदा दस्तावेज़ में टेक्स्ट डालकर, उसे स्टाइल कर सकते हैं.

बैच की जानकारी

एक साथ कई अनुरोधों में किए जाने वाले अनुरोधों में, batchUpdate के एक तरीके का कॉल शामिल होता है. इसमें कई सब-अनुरोध शामिल होते हैं. उदाहरण के लिए, किसी दस्तावेज़ को जोड़ना और फिर उसे फ़ॉर्मैट करना.

हर अनुरोध को लागू करने से पहले उसकी पुष्टि की जाती है. बैच अपडेट में शामिल सभी सब-अनुरोध अपने-आप लागू होते हैं. इसका मतलब है कि अगर कोई अनुरोध मान्य नहीं है, तो पूरा अपडेट पूरा नहीं हो पाता और कोई भी (संभावित तौर पर निर्भर) बदलाव लागू नहीं होता है.

कुछ अनुरोधों में, लागू किए गए अनुरोधों के बारे में जानकारी दी जाती है. उदाहरण के लिए, ऑब्जेक्ट जोड़ने के लिए, बैच अपडेट करने के सभी अनुरोध से जवाब मिलते हैं. इससे, जोड़े गए नए ऑब्जेक्ट का मेटाडेटा ऐक्सेस किया जा सकता है, जैसे कि आईडी या टाइटल.

इस तरीके से, कई सब-अनुरोधों के साथ एक एपीआई बैच अपडेट करने के एक अनुरोध का इस्तेमाल करके, पूरा Google दस्तावेज़ बनाया जा सकता है.

बैच अनुरोध का फ़ॉर्मैट

अनुरोध, एक JSON अनुरोध होता है. इसमें एक ज़रूरी प्रॉपर्टी के साथ, नेस्ट किए गए कई सबअनुरोध होते हैं: requests. ये अनुरोध, अलग-अलग अनुरोधों के हिसाब से बनाए जाते हैं. हर अनुरोध, अनुरोध ऑब्जेक्ट और उसकी प्रॉपर्टी को शामिल करने के लिए JSON का इस्तेमाल करता है.

बैच रिस्पॉन्स का फ़ॉर्मैट

एक साथ कई अनुरोधों के लिए response का फ़ॉर्मैट, अनुरोध के फ़ॉर्मैट की तरह ही होता है. सर्वर के रिस्पॉन्स में, एक रिस्पॉन्स ऑब्जेक्ट का पूरा जवाब शामिल होता है.

JSON ऑब्जेक्ट की मुख्य प्रॉपर्टी का नाम replies है. रिस्पॉन्स, एक कैटगरी में दिखाए जाते हैं. हर अनुरोध के लिए रिस्पॉन्स, संबंधित अनुरोध के इंडेक्स ऑर्डर में शामिल होता है. कुछ अनुरोधों के जवाब नहीं मिलते और ऐरे इंडेक्स में जवाब नहीं दिया जाता.

उदाहरण

इस उदाहरण में, Docs API के साथ बैच बनाने की सुविधा का इस्तेमाल दिखाया गया है.

अनुरोध

एक साथ कई अनुरोध भेजने के इस उदाहरण में, यह जानकारी दी गई है:

  • InsertTextRequest का इस्तेमाल करके, किसी मौजूदा दस्तावेज़ की शुरुआत में "Hello World" टेक्स्ट, 1 के इंडेक्स Location के साथ डालें.
  • UpdateTextStyleRequest का इस्तेमाल करके "हैलो" शब्द अपडेट करें. startIndex और endIndex, सेगमेंट में फ़ॉर्मैट किए गए टेक्स्ट का range तय करते हैं.`
  • textStyle का इस्तेमाल करके, फ़ॉन्ट स्टाइल को बोल्ड और रंग को नीला पर सेट करें.
{
   "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"
         }
      }
   ]
}

जवाब

बैच रिक्वेस्ट का यह उदाहरण यह जानकारी दिखाता है कि बैच रिक्वेस्ट में शामिल हर सब-अनुरोध को कैसे लागू किया गया. ध्यान दें कि InsertTextRequest और UpdateTextStyleRequest, दोनों में जवाब शामिल नहीं है, इसलिए [0] और [1] पर ऐरे की इंडेक्स वैल्यू में कर्ली ब्रैकेट होंगे. एक साथ कई अनुरोध करने पर, WriteControl का असर पड़ता है. इससे पता चलता है कि लिखने के अनुरोध कैसे पूरे किए गए थे.

{
   "replies":[
      {
         
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId":`REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}