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

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

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

खास जानकारी

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

उन स्थितियों के उदाहरण जब आपको एक साथ कई अनुरोध भेजने की ज़रूरत पड़ सकती है:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

नीचे दिया गया उदाहरण, लोग एपीआई की मदद से बैच बनाने की सुविधा का इस्तेमाल करता है.

बैच अनुरोध का उदाहरण

POST /batch HTTP/1.1
accept-encoding: gzip, deflate
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary="batch_people"
Content-Length: total_content_length


--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

POST /v1/people:createContact HTTP/1.1
Content-Type: application/json
Content-Length: part_content_length
Accept: application/json
{
  "names": [{ "givenName": "John", "familyName": "Doe" }]
}

--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1
Accept: application/json
--batch_people--

बैच में दिए गए जवाब का उदाहरण

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

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Date: Tue, 22 Jan 2020 18:56:00 GMT
Expires: Tue, 22 Jan 2020 18:56:00 GMT
Cache-Control: private


--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-1

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resourceName": "people/c11111111111111",
  "etag": "1111",
  "names": [{ "givenName": "John", "familyName": "Doe" }]
}

--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-2

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resourceName": "people/c123456789012345",
  "etag": "1234",
  "emailAddresses": [{ "value": "[e-mail]" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--