बैच अनुरोध

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

खास जानकारी

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

इस उदाहरण में, Sheets API के साथ बैचिंग का इस्तेमाल दिखाया गया है.

अनुरोध

इस उदाहरण बैच अनुरोध में, यह बताया गया है कि:

• AddSheetRequest का इस्तेमाल करके, किसी मौजूदा स्प्रेडशीट में 12345 के sheetId वाली शीट जोड़ें.
• UpdateCellsRequest का इस्तेमाल करके, नई शीट में डेटा जोड़ें. डेटा को सेल A1 से जोड़ना शुरू करें.
• नई शीट में namedRange या फ़िल्टर व्यू जोड़ें.

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

बैच अपडेट के अनुरोध के टाइप की सूची देखने के लिए, बैच अपडेट के ऑपरेशन में दी गई टेबल देखें. इस टेबल में, अनुरोध के टाइप को अलग-अलग कैटगरी में बांटा गया है.

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

जवाब

इस उदाहरण में बैच रिस्पॉन्स दिखाया गया है. इसमें यह जानकारी दी गई है कि बैच अनुरोध में मौजूद हर उप-अनुरोध को कैसे लागू किया गया. ध्यान दें कि UpdateCellsRequest में कोई जवाब नहीं है. इसलिए, [1] पर मौजूद ऐरे की इंडेक्स वैल्यू में खाली घुंघराले ब्रैकेट शामिल हैं.

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]