बैच अनुरोध भेजना

खास जानकारी

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

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

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

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

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

ध्यान दें: डायरेक्ट्री एपीआई का बैच सिस्टम, वही सिंटैक्स इस्तेमाल करता है जो 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- स्ट्रिंग होती है, जैसा कि इस उदाहरण में दिखाया गया है.

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

उदाहरण

नीचे दिए गए उदाहरण में, एक जेनरिक (काल्पनिक) डेमो एपीआई के साथ एक साथ कई बैच बनाने का तरीका दिखाया गया है. इस एपीआई को Farm API कहा जाता है. हालांकि, ये सिद्धांत Directory 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--