बैच अनुरोध

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

इस दस्तावेज़ में, एचटीटीपी अनुरोध भेजकर बैच में अनुरोध करने के बारे में बताया गया है. अगर बैच में अनुरोध करने के लिए, Google की क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो क्लाइंट लाइब्रेरी का दस्तावेज़ देखें.

खास जानकारी

क्लाइंट के हर एचटीटीपी कनेक्शन से, कुछ ओवरहेड होता है. Gmail API, बैचिंग की सुविधा देता है. इससे, क्लाइंट कई एपीआई कॉल को एक एचटीटीपी अनुरोध में शामिल कर सकता है.

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

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

हर मामले में, हर कॉल को अलग-अलग भेजने के बजाय, उन्हें एक एचटीटीपी अनुरोध में ग्रुप किया जा सकता है. अंदर के सभी अनुरोध, एक ही Google API पर जाने चाहिए.

बैच में किए गए एक अनुरोध में, ज़्यादा से ज़्यादा 100 कॉल शामिल किए जा सकते हैं. अगर इससे ज़्यादा कॉल करने हैं, तो बैच में कई अनुरोध करें.

ध्यान दें: Gmail API के लिए बैच सिस्टम, OData बैच प्रोसेसिंग सिस्टम के सिंटैक्स का इस्तेमाल करता है. हालांकि, सिमैंटिक्स अलग-अलग होते हैं.

ध्यान दें: बैच के साइज़ बड़े होने पर, रेट लिमिटिंग ट्रिगर होने की संभावना होती है. 50 से ज़्यादा अनुरोधों वाले बैच भेजने का सुझाव नहीं दिया जाता.

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

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

ध्यान दें: बैच में शामिल किए गए n अनुरोधों को, इस्तेमाल की सीमा में एक अनुरोध के तौर पर नहीं, बल्कि n अनुरोधों के तौर पर गिना जाता है. प्रोसेस करने से पहले, बैच में किए गए अनुरोध को कई अनुरोधों में बांटा जाता है.

बैच में किए गए अनुरोध का फ़ॉर्मैट

बैच में किया गया अनुरोध, एक सामान्य एचटीटीपी अनुरोध होता है. इसमें multipart/mixed कॉन्टेंट टाइप का इस्तेमाल करके, Gmail API के कई कॉल शामिल होते हैं. उस मुख्य एचटीटीपी अनुरोध में, हर हिस्से में नेस्ट किया गया एचटीटीपी अनुरोध शामिल होता है.

हर हिस्सा, अपने Content-Type: application/http एचटीटीपी हेडर से शुरू होता है. इसमें, Content-ID हेडर भी शामिल किया जा सकता है. हालांकि, यह ज़रूरी नहीं है. हालांकि, पार्ट हेडर सिर्फ़ हिस्से की शुरुआत को मार्क करने के लिए होते हैं. ये नेस्ट किए गए अनुरोध से अलग होते हैं. सर्वर, बैच में किए गए अनुरोध को अलग-अलग अनुरोधों में बांटने के बाद, पार्ट हेडर को अनदेखा कर देता है.

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

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

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

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

बैच में किए गए अनुरोध का जवाब

सर्वर का जवाब, multipart/mixed कॉन्टेंट टाइप वाला एक सामान्य एचटीटीपी जवाब होता है. इसमें शामिल हर हिस्सा, बैच में किए गए अनुरोध में शामिल किसी एक अनुरोध का जवाब होता है. जवाब, अनुरोधों के क्रम में ही मिलते हैं.

अनुरोध में शामिल हिस्सों की तरह, जवाब के हर हिस्से में एक सामान्य एचटीटीपी जवाब शामिल होता है. इसमें स्टेटस कोड, हेडर, और कोड शामिल होते हैं. अनुरोध में शामिल हिस्सों की तरह, जवाब के हर हिस्से से पहले Content-Type हेडर होता है. इससे हिस्से की शुरुआत का पता चलता है.

अगर अनुरोध के किसी हिस्से में Content-ID हेडर शामिल था, तो जवाब के उस हिस्से में भी Content-ID हेडर शामिल होता है. इसकी वैल्यू, ओरिजनल वैल्यू से पहले response- स्ट्रिंग के साथ होती है. ज़्यादा जानने के लिए, यहां दिया गया उदाहरण देखें.

ध्यान दें: सर्वर, आपके कॉल को किसी भी क्रम में प्रोसेस कर सकता है. यह ज़रूरी नहीं है कि कॉल, उसी क्रम में प्रोसेस किए जाएं जिस क्रम में आपने उन्हें भेजा है. अगर आपको यह पक्का करना है कि दो कॉल किसी खास क्रम में प्रोसेस किए जाएं, तो उन्हें एक अनुरोध में नहीं भेजा जा सकता. इसके बजाय, पहला कॉल अलग से भेजें. इसके बाद, पहला कॉल प्रोसेस होने के बाद मिलने वाले जवाब का इंतज़ार करें. इसके बाद, दूसरा कॉल भेजें.

उदाहरण

यहां दिए गए उदाहरण में, बैचिंग का इस्तेमाल दिखाया गया है. इसके लिए, Farm API नाम के फ़िक्शनल (काल्पनिक) डेमो एपीआई का इस्तेमाल किया गया है. हालांकि, यही सिद्धांत Gmail API पर भी लागू होते हैं.

बैच में किए गए अनुरोध का उदाहरण

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

बैच में किए गए अनुरोध के जवाब का उदाहरण

यह पिछले सेक्शन में दिए गए अनुरोध के उदाहरण का जवाब है.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--