बैच अनुरोध

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

खास जानकारी

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

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

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

सीमाएं, पुष्टि, और डिपेंडेंसी से जुड़ी बातें

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

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

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

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

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

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

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

एक साथ ग्रुप या बैच में भेजे गए अनुरोध का फ़ॉर्मैट

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

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

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

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

उदाहरण

यहां दिए गए कोड सैंपल में, Docs API के साथ बैचिंग का इस्तेमाल दिखाया गया है.

अनुरोध

इस उदाहरण में बैच अनुरोध के बारे में बताया गया है. इससे आपको यह जानकारी मिलेगी कि:

  • InsertTextRequest का इस्तेमाल करके, किसी मौजूदा दस्तावेज़ की शुरुआत में "Hello World" टेक्स्ट डालें. साथ ही, इंडेक्स location को 1 पर सेट करें.

  • UpdateTextStyleRequest का इस्तेमाल करके, "नमस्ते" शब्द को अपडेट करें. startIndex और endIndex, सेगमेंट में फ़ॉर्मैट किए गए टेक्स्ट के range को तय करते हैं.

  • textStyle का इस्तेमाल करके, सिर्फ़ "Hello" शब्द के लिए फ़ॉन्ट स्टाइल को बोल्ड और रंग को नीला पर सेट करें.

  • 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`
}