बैच अनुरोध

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

खास जानकारी

आपके क्लाइंट के हर कनेक्शन से कुछ ओवरहेड होता है. 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,
               "tabId":TAB_ID
            },
            "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"
  }
}

TAB_ID और REQUIRED_REVISION_ID की जगह, उस दस्तावेज़ के टैब आईडी और बदलाव आईडी डालें जिस पर लिखने का अनुरोध किया गया है.

जवाब

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

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