बैच अनुरोध

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

खास जानकारी

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

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

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

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

यहां उन अन्य आइटम की सूची दी गई है जिन पर बैच अपडेट लागू करते समय ध्यान रखना चाहिए:

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

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

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

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

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

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

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

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

बैच में दिए गए जवाब का फ़ॉर्मैट

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

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

उदाहरण

नीचे दिए गए उदाहरण में, Sheets API की मदद से एक साथ कई अनुरोध भेजने की सुविधा के इस्तेमाल के बारे में बताया गया है.

अनुरोध

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

• AddSheetRequest का इस्तेमाल करके, 12345 के sheetId वाली किसी मौजूदा स्प्रेडशीट में शीट जोड़ें.
• सेल A1 से शुरू करते हुए, UpdateCellsRequest का इस्तेमाल करके नई शीट में डेटा जोड़ें.
• नई शीट में 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
            }
         }
      }
   }
]