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