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

खास जानकारी

आपका क्लाइंट, हर एचटीटीपी कनेक्शन से एक तय रकम का ओवरहेड देता है. 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--