बैच अनुरोध

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

खास जानकारी

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

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

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

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

एक साथ कई आइटम अपडेट करने की सुविधा का इस्तेमाल करते समय, इन बातों का ध्यान रखें:

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

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

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

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

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

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

एक साथ कई अनुरोध करने का फ़ॉर्मैट

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

एक साथ कई अनुरोधों के जवाब का फ़ॉर्मैट

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

मुख्य 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`
}