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

बैच में अनुरोध

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

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

खास जानकारी

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

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

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

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

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

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

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

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

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

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

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

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

हर हिस्से अपने 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--