इस दस्तावेज़ में, एपीआई कॉल को एक साथ बैच करने का तरीका बताया गया है. इससे आपके क्लाइंट को बनाने वाले एचटीटीपी कनेक्शन की संख्या कम हो जाती है.
इस दस्तावेज़ में खास तौर पर, एचटीटीपी अनुरोध भेजकर बैच में अनुरोध करने के बारे में बताया गया है. इसके बजाय, अगर बैच रिक्वेस्ट के लिए Google की क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो क्लाइंट लाइब्रेरी का दस्तावेज़ देखें.
खास जानकारी
आपके क्लाइंट के हर एचटीटीपी कनेक्शन से कुछ ओवरहेड होता है. Enterprise License Manager API, बैच में काम करता है. इससे आपके क्लाइंट को एक ही एचटीटीपी अनुरोध में कई एपीआई कॉल करने की सुविधा मिलती है.
ऐसी स्थितियों के उदाहरण जिनमें बैच में डेटा अपलोड करने की सुविधा का इस्तेमाल किया जा सकता है:
- आपने हाल ही में एपीआई का इस्तेमाल शुरू किया है और आपके पास अपलोड करने के लिए काफ़ी डेटा है.
- आपका ऐप्लिकेशन ऑफ़लाइन (इंटरनेट से कनेक्ट नहीं) होने के दौरान, किसी उपयोगकर्ता ने डेटा में बदलाव किया. इसलिए, आपके ऐप्लिकेशन को अपने स्थानीय डेटा को सर्वर के साथ सिंक करना होगा. इसके लिए, उसे कई अपडेट भेजने होंगे और डेटा मिटाना होगा.
हर मामले में, हर कॉल को अलग से भेजने के बजाय, उन्हें एक ही एचटीटीपी अनुरोध में ग्रुप किया जा सकता है. सभी इनर अनुरोध, एक ही Google API को भेजे जाने चाहिए.
एक बार में ज़्यादा से ज़्यादा 1,000 कॉल के लिए अनुरोध किया जा सकता है. अगर आपको इससे ज़्यादा कॉल करने हैं, तो एक से ज़्यादा बैच अनुरोधों का इस्तेमाल करें.
ध्यान दें: Enterprise License Manager API के लिए बैच सिस्टम, OData बैच प्रोसेसिंग सिस्टम के जैसे ही सिंटैक्स का इस्तेमाल करता है. हालांकि, इनमें सेमेटिक्स अलग-अलग होते हैं.
बैच की जानकारी
बैच रिक्वेस्ट में एक एचटीटीपी रिक्वेस्ट में कई एपीआई कॉल शामिल होते हैं. इसे एपीआई डिस्कवरी दस्तावेज़ में बताए गए batchPath
पर भेजा जा सकता है. डिफ़ॉल्ट पाथ /batch/api_name/api_version
है. इस सेक्शन में, बैच सिंटैक्स के बारे में पूरी जानकारी दी गई है. इसके बाद, एक उदाहरण दिया गया है.
ध्यान दें: एक साथ किए गए n अनुरोधों के सेट को, इस्तेमाल की सीमा में एक अनुरोध के तौर पर नहीं, बल्कि n अनुरोधों के तौर पर गिना जाता है. एक साथ कई अनुरोधों को प्रोसेस करने से पहले, उन्हें अनुरोधों के एक सेट में अलग कर दिया जाता है.
एक साथ कई अनुरोध करने का फ़ॉर्मैट
बैच रिक्वेस्ट, एक स्टैंडर्ड एचटीटीपी रिक्वेस्ट होता है. इसमें multipart/mixed
कॉन्टेंट टाइप का इस्तेमाल करके, Enterprise License Manager API के कई कॉल शामिल होते हैं. उस मुख्य एचटीटीपी अनुरोध के हर हिस्से में, नेस्ट किया गया एचटीटीपी अनुरोध मौजूद होता है.
हर हिस्सा अपने Content-Type: application/http
एचटीटीपी हेडर से शुरू होता है. इसमें वैकल्पिक Content-ID
हेडर भी हो सकता है. हालांकि, पार्ट हेडर सिर्फ़ पार्ट की शुरुआत को मार्क करने के लिए होते हैं. ये नेस्ट किए गए अनुरोध से अलग होते हैं. जब सर्वर, बैच रिक्वेस्ट को अलग-अलग रिक्वेस्ट में अनरैप कर देता है, तो पार्ट हेडर को अनदेखा कर दिया जाता है.
हर हिस्से का मुख्य हिस्सा, एक पूरा एचटीटीपी अनुरोध होता है. इसमें अपनी क्रिया, यूआरएल, हेडर, और मुख्य हिस्से का इस्तेमाल किया जाता है. एचटीटीपी अनुरोध में सिर्फ़ यूआरएल का पाथ हिस्सा शामिल होना चाहिए. एक साथ कई अनुरोधों में पूरे यूआरएल शामिल करने की अनुमति नहीं है.
बाहरी बैच अनुरोध के लिए एचटीटीपी हेडर, बैच में मौजूद हर अनुरोध पर लागू होते हैं. हालांकि, Content-Type
जैसे Content-
हेडर पर ये लागू नहीं होते. अगर आउटर अनुरोध और किसी एक कॉल, दोनों में कोई एचटीटीपी हेडर दिया जाता है, तो किसी एक कॉल के हेडर की वैल्यू, आउटर बैच अनुरोध के हेडर की वैल्यू को बदल देती है. किसी कॉल के लिए सेट किए गए हेडर, सिर्फ़ उस कॉल पर लागू होते हैं.
उदाहरण के लिए, अगर आपने किसी खास कॉल के लिए अनुमति वाला हेडर दिया है, तो वह हेडर सिर्फ़ उस कॉल पर लागू होगा. अगर बाहरी अनुरोध के लिए अनुमति हेडर दिया जाता है, तो वह हेडर सभी अलग-अलग कॉल पर लागू होता है. ऐसा तब तक होता है, जब तक वे अपने अनुमति हेडर से उसे बदल नहीं देते.
जब सर्वर को एक साथ कई अनुरोध मिलते हैं, तो वह हर हिस्से पर बाहरी अनुरोध के क्वेरी पैरामीटर और हेडर (जैसा कि ज़रूरी हो) लागू करता है. इसके बाद, हर हिस्से को एक अलग एचटीटीपी अनुरोध के तौर पर इस्तेमाल करता है.
बैच में भेजे गए अनुरोध का जवाब
सर्वर का रिस्पॉन्स, multipart/mixed
कॉन्टेंट टाइप वाला एक स्टैंडर्ड एचटीटीपी रिस्पॉन्स होता है. इसमें हर सेक्शन, एक साथ किए गए अनुरोधों में से किसी एक अनुरोध का जवाब होता है. यह जवाब, अनुरोधों के क्रम में ही दिया जाता है.
अनुरोध के हिस्सों की तरह ही, जवाब के हर हिस्से में एक पूरा एचटीटीपी जवाब होता है. इसमें स्टेटस कोड, हेडर, और मुख्य हिस्सा शामिल होता है. अनुरोध के हिस्सों की तरह ही, जवाब के हर हिस्से के पहले एक Content-Type
हेडर होता है, जो हिस्से की शुरुआत को मार्क करता है.
अगर अनुरोध के किसी हिस्से में Content-ID
हेडर है, तो रिस्पॉन्स के हिसाब से उस हिस्से में मेल खाने वाला Content-ID
हेडर होता है. इसमें, ओरिजनल वैल्यू के पहले response-
स्ट्रिंग होती है, जैसा कि इस उदाहरण में दिखाया गया है.
ध्यान दें: सर्वर आपके कॉल किसी भी क्रम में कर सकता है. यह उम्मीद न करें कि वे उसी क्रम में लागू होंगे जिस क्रम में आपने उन्हें तय किया है. अगर आपको यह पक्का करना है कि दो कॉल किसी तय क्रम में हों, तो उन्हें एक ही अनुरोध में नहीं भेजा जा सकता. इसके बजाय, पहले कॉल को अलग से भेजें. इसके बाद, दूसरे कॉल को भेजने से पहले, पहले कॉल के जवाब का इंतज़ार करें.
उदाहरण
यहां दिए गए उदाहरण में, फ़ार्म एपीआई नाम के सामान्य (काल्पनिक) डेमो एपीआई के साथ, एक साथ कई अनुरोध भेजने की सुविधा का इस्तेमाल दिखाया गया है. हालांकि, Enterprise License Manager 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--