इस पेज का अनुवाद Cloud Translation API से किया गया है.

बैचिंग अनुरोध

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

इस दस्तावेज़ में, एचटीटीपी अनुरोध भेजकर, एक साथ कई अनुरोध करने के बारे में बताया गया है. अगर बैच रिक्वेस्ट करने के लिए, 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-Type जैसे Content- हेडर पर ये लागू नहीं होते. अगर बाहरी अनुरोध और किसी एक कॉल, दोनों में कोई एचटीटीपी हेडर दिया जाता है, तो किसी एक कॉल के हेडर की वैल्यू, बाहरी बैच अनुरोध के हेडर की वैल्यू को बदल देती है. किसी कॉल के लिए सेट किए गए हेडर, सिर्फ़ उस कॉल पर लागू होते हैं.

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

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

एक साथ कई अनुरोध करने पर मिलने वाला जवाब

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

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

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

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

उदाहरण

यहां दिए गए उदाहरण में, फ़ार्म एपीआई नाम के सामान्य (काल्पनिक) डेमो एपीआई के साथ, एक साथ कई अनुरोध भेजने की सुविधा का इस्तेमाल दिखाया गया है. हालांकि, 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--