बैच अनुरोध

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

खास जानकारी

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