बैच अनुरोध

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

खास जानकारी

आपका क्लाइंट हर कनेक्शन से तय मात्रा में ओवरहेड बनाता है. 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`
}