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

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

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

खास जानकारी

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

ऐसी स्थितियों के उदाहरण जिनमें बैच में अपलोड करने की सुविधा का इस्तेमाल किया जा सकता है:

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

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

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

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

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

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

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

एक साथ कई अनुरोध करने का फ़ॉर्मैट

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

इस उदाहरण में, People API के साथ एक साथ कई अनुरोध करने का तरीका बताया गया है.

एक साथ कई अनुरोध करने का उदाहरण

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": "jane.doe@gmail.com" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--