प्रदर्शन सुधारें

gzip का इस्तेमाल करके कंप्रेस करना

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

gzip से एन्कोड किया गया रिस्पॉन्स पाने के लिए, आपको दो काम करने होंगे: Accept-Encoding हेडर सेट करना और अपने यूज़र एजेंट में स्ट्रिंग gzip शामिल करने के लिए उसमें बदलाव करना. यहां gzip कंप्रेसन की सुविधा चालू करने के लिए, सही तरीके से बनाए गए एचटीटीपी हेडर का उदाहरण दिया गया है:

Accept-Encoding: gzip
User-Agent: my program (gzip)

कुछ संसाधनों के साथ काम करना

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

कुछ हिस्से के लिए अनुरोध दो तरह के होते हैं:

• कुछ हिस्से का जवाब: यह एक ऐसा अनुरोध है जिसमें यह बताया जाता है कि रिस्पॉन्स में कौनसे फ़ील्ड शामिल करने हैं. इसके लिए, fields अनुरोध पैरामीटर का इस्तेमाल करें.
• पैच: अपडेट का अनुरोध, जिसमें सिर्फ़ वे फ़ील्ड भेजे जाते हैं जिनमें बदलाव करना है. इसके लिए, PATCH एचटीटीपी वर्ब का इस्तेमाल करें.

कुछ डेटा के लिए अनुरोध करने के बारे में ज़्यादा जानकारी, यहां दिए गए सेक्शन में दी गई है.

अधूरे जवाब

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

कुछ हिस्से के जवाब का अनुरोध करने के लिए, fields अनुरोध पैरामीटर का इस्तेमाल करके वे फ़ील्ड बताएं जो आपको वापस चाहिए. इस पैरामीटर का इस्तेमाल, जवाब के तौर पर डेटा दिखाने वाले किसी भी अनुरोध के साथ किया जा सकता है.

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

उदाहरण

इस उदाहरण में, सामान्य (काल्पनिक) "डेमो" एपीआई के साथ fields पैरामीटर का इस्तेमाल दिखाया गया है.

सामान्य अनुरोध: इस एचटीटीपी GET अनुरोध में fields पैरामीटर शामिल नहीं होता और पूरा संसाधन दिखाया जाता है.

https://www.googleapis.com/demo/v1

संसाधन का पूरा डेटा: संसाधन के पूरे डेटा में, नीचे दिए गए फ़ील्ड के साथ-साथ कई अन्य फ़ील्ड शामिल होते हैं. हालांकि, हमने इन्हें छोटा रखने के लिए शामिल नहीं किया है.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

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

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

कुछ हद तक जवाब: ऊपर दिए गए अनुरोध के जवाब में, सर्वर सिर्फ़ 'किस तरह का' जानकारी के साथ-साथ, आइटम के छोटे किए गए कलेक्शन का जवाब भेजता है. इस कलेक्शन में, हर आइटम में सिर्फ़ एचटीएमएल टाइटल और लंबाई की जानकारी शामिल होती है.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

ध्यान दें कि रिस्पॉन्स एक JSON ऑब्जेक्ट होता है. इसमें सिर्फ़ चुने गए फ़ील्ड और उनके पैरंट ऑब्जेक्ट शामिल होते हैं.

इसके बाद, fields पैरामीटर को फ़ॉर्मैट करने का तरीका बताया गया है. इसके बाद, रिस्पॉन्स में क्या दिखता है, इस बारे में ज़्यादा जानकारी दी गई है.

फ़ील्ड पैरामीटर सिंटैक्स की खास जानकारी

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

• एक से ज़्यादा फ़ील्ड चुनने के लिए, कॉमा से अलग की गई सूची का इस्तेमाल करें.
• a फ़ील्ड में नेस्ट किए गए b फ़ील्ड को चुनने के लिए, a/b का इस्तेमाल करें. b फ़ील्ड में नेस्ट किए गए c फ़ील्ड को चुनने के लिए, a/b/c का इस्तेमाल करें.
  

  अपवाद: "data" रैपर का इस्तेमाल करने वाले एपीआई रिस्पॉन्स के लिए, जहां रिस्पॉन्स data: { ... } जैसे दिखने वाले data ऑब्जेक्ट में नेस्ट किया गया है, तो fields स्पेसिफ़िकेशन में "data" शामिल न करें. data/a/b जैसे फ़ील्ड की जानकारी वाले डेटा ऑब्जेक्ट को शामिल करने पर गड़बड़ी होती है. इसके बजाय, a/b जैसी fields स्पेसिफ़िकेशन का इस्तेमाल करें.

• ऐरे या ऑब्जेक्ट के खास सब-फ़ील्ड के सेट का अनुरोध करने के लिए, सब-सिलेक्टर का इस्तेमाल करें. इसके लिए, एक्सप्रेशन को ब्रैकेट "( )" में रखें.

  उदाहरण के लिए: fields=items(id,author/email), आइटम कलेक्शन में मौजूद हर एलिमेंट के लिए सिर्फ़ आइटम आईडी और लेखक का ईमेल पता दिखाता है. आपके पास एक सब-फ़ील्ड तय करने का विकल्प भी है, जहां fields=items(id), fields=items/id के बराबर है.

• अगर ज़रूरी हो, तो फ़ील्ड के विकल्पों में वाइल्डकार्ड का इस्तेमाल करें.

  उदाहरण के लिए: fields=items/pagemap/*, पेजमैप में मौजूद सभी ऑब्जेक्ट चुनता है.

फ़ील्ड पैरामीटर का इस्तेमाल करने के और उदाहरण

यहां दिए गए उदाहरणों में बताया गया है कि fields पैरामीटर की वैल्यू, रिस्पॉन्स पर कैसे असर डालती है.

ध्यान दें: fields पैरामीटर की वैल्यू को कोड में बदलना ज़रूरी है, जैसे कि सभी क्वेरी पैरामीटर की वैल्यू को कोड में बदलना ज़रूरी है. इस दस्तावेज़ में दिए गए उदाहरणों में, एन्कोडिंग को शामिल नहीं किया गया है, ताकि उन्हें आसानी से पढ़ा जा सके.

उन फ़ील्ड की पहचान करें जिन्हें आपको दिखाना है या फ़ील्ड चुनें.

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

कलेक्शन-लेवल के कुछ उदाहरण यहां दिए गए हैं:

उदाहरण	असर
items	आइटम कलेक्शन में मौजूद सभी एलिमेंट दिखाता है. इसमें हर एलिमेंट के सभी फ़ील्ड शामिल होते हैं, लेकिन कोई अन्य फ़ील्ड नहीं.
etag,items	आइटम कलेक्शन में मौजूद etag फ़ील्ड और सभी एलिमेंट दिखाता है.
items/title	आइटम कलेक्शन में मौजूद सभी एलिमेंट के लिए, सिर्फ़ title फ़ील्ड दिखाता है. जब भी नेस्ट किया गया कोई फ़ील्ड दिखाया जाता है, तो रिस्पॉन्स में उस फ़ील्ड को शामिल करने वाले पैरंट ऑब्जेक्ट भी शामिल होते हैं. पैरंट फ़ील्ड में तब तक कोई दूसरा चाइल्ड फ़ील्ड शामिल नहीं होता, जब तक कि उसे साफ़ तौर पर नहीं चुना जाता.
context/facets/label	यह फ़ंक्शन, facets कलेक्शन के सभी सदस्यों के लिए सिर्फ़ label फ़ील्ड दिखाता है. यह कलेक्शन, context ऑब्जेक्ट के तहत नेस्ट होता है.
items/pagemap/*/title	items कलेक्शन के हर एलिमेंट के लिए, pagemap के चाइल्ड ऑब्जेक्ट का सिर्फ़ title फ़ील्ड (अगर मौजूद हो) दिखाता है.

संसाधन-लेवल के कुछ उदाहरण यहां दिए गए हैं:

उदाहरण	असर
title	अनुरोध किए गए संसाधन का title फ़ील्ड दिखाता है.
author/uri	अनुरोध किए गए संसाधन में, author ऑब्जेक्ट का uri सब-फ़ील्ड दिखाता है.
links/*/href	links के चाइल्ड ऑब्जेक्ट के href फ़ील्ड को दिखाता है.

सब-चुनी गई वैल्यू का इस्तेमाल करके, सिर्फ़ चुनिंदा फ़ील्ड के कुछ हिस्सों का अनुरोध करें.

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

उदाहरण	असर
items(title,author/uri)	आइटम के ऐरे में मौजूद हर एलिमेंट के लिए, सिर्फ़ title और लेखक की uri वैल्यू दिखाता है.

अधूरे जवाबों को मैनेज करना

जब कोई सर्वर, fields क्वेरी पैरामीटर वाले मान्य अनुरोध को प्रोसेस कर लेता है, तो वह अनुरोध किए गए डेटा के साथ एचटीटीपी 200 OK स्टेटस कोड भेजता है. अगर fields क्वेरी पैरामीटर में कोई गड़बड़ी है या वह अमान्य है, तो सर्वर एचटीटीपी 400 Bad Request स्टेटस कोड के साथ-साथ गड़बड़ी का मैसेज भी दिखाता है. इस मैसेज से उपयोगकर्ता को पता चलता है कि फ़ील्ड के उनके चुने गए विकल्प में क्या गड़बड़ी है (उदाहरण के लिए, "Invalid field selection a/b").

यहां ऊपर दिए गए शुरुआती सेक्शन में दिखाए गए, अधूरे जवाब का उदाहरण दिया गया है. अनुरोध में fields पैरामीटर का इस्तेमाल करके यह तय किया जाता है कि कौनसे फ़ील्ड दिखाने हैं.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

अधूरा जवाब ऐसा दिखता है:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

ध्यान दें: डेटा पेजेशन के लिए क्वेरी पैरामीटर (उदाहरण के लिए, maxResults और nextPageToken) का इस्तेमाल करने वाले एपीआई के लिए, हर क्वेरी के नतीजों को मैनेज किए जा सकने वाले साइज़ में कम करने के लिए, उन पैरामीटर का इस्तेमाल करें. ऐसा न करने पर, हो सकता है कि आंशिक जवाब देने से मिलने वाले परफ़ॉर्मेंस फ़ायदे न मिलें.

पैच (कुछ हिस्से का अपडेट)

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

नीचे दिए गए छोटे उदाहरण में दिखाया गया है कि पैच का इस्तेमाल करके, छोटा अपडेट करने के लिए, आपको कितना कम डेटा भेजना पड़ता है.

उदाहरण

इस उदाहरण में, किसी सामान्य (काल्पनिक) "डेमो" एपीआई संसाधन के सिर्फ़ टाइटल को अपडेट करने के लिए, एक आसान पैच अनुरोध दिखाया गया है. रिसॉर्स में टिप्पणी, विशेषताओं का सेट, स्थिति, और कई अन्य फ़ील्ड भी होते हैं. हालांकि, इस अनुरोध में सिर्फ़ title फ़ील्ड भेजा जाता है, क्योंकि इसमें ही बदलाव किया जा रहा है:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

जवाब:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

सर्वर, अपडेट किए गए संसाधन की पूरी जानकारी के साथ-साथ 200 OK स्टेटस कोड दिखाता है. पैच अनुरोध में सिर्फ़ title फ़ील्ड शामिल किया गया था, इसलिए यह वैल्यू ही पहले से अलग है.

ध्यान दें: पैच के साथ कुछ हिस्से का जवाब fields पैरामीटर का इस्तेमाल करने पर, अपडेट के अनुरोधों को ज़्यादा असरदार बनाया जा सकता है. पैच अनुरोध से सिर्फ़ अनुरोध का साइज़ कम होता है. कुछ हिस्से का जवाब देने से, जवाब का साइज़ कम हो जाता है. इसलिए, दोनों दिशाओं में भेजे जाने वाले डेटा की संख्या कम करने के लिए, fields पैरामीटर के साथ पैच अनुरोध का इस्तेमाल करें.

पैच अनुरोध के बारे में जानकारी

पैच अनुरोध के मुख्य हिस्से में, सिर्फ़ वे संसाधन फ़ील्ड शामिल होते हैं जिनमें आपको बदलाव करना है. कोई फ़ील्ड तय करते समय, आपको उसमें पैरंट ऑब्जेक्ट शामिल करने होंगे. ठीक उसी तरह जैसे पैरंट ऑब्जेक्ट, कुछ हिस्से के जवाब के साथ दिखाए जाते हैं. आपने जो डेटा भेजा है उसे पैरंट ऑब्जेक्ट के डेटा में मर्ज कर दिया जाता है. हालांकि, ऐसा तब ही होता है, जब कोई पैरंट ऑब्जेक्ट हो.

• जोड़ें: कोई नया फ़ील्ड जोड़ने के लिए, नया फ़ील्ड और उसकी वैल्यू डालें.
• बदलें: किसी मौजूदा फ़ील्ड की वैल्यू बदलने के लिए, फ़ील्ड चुनें और उसे नई वैल्यू पर सेट करें.
  
• मिटाएं: किसी फ़ील्ड को मिटाने के लिए, फ़ील्ड चुनें और उसे null पर सेट करें. उदाहरण के लिए, "comment": null. अगर कोई ऑब्जेक्ट बदला जा सकता है, तो उसे null पर सेट करके भी मिटाया जा सकता है. अगर Java API क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो इसके बजाय Data.NULL_STRING का इस्तेमाल करें. ज़्यादा जानकारी के लिए, JSON null देखें.

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

रीड-बदलाव करें-लिखें साइकल में पैच का इस्तेमाल करना

जिस डेटा में बदलाव करना है उसके साथ कुछ जवाब वापस पाकर शुरुआत करना एक अच्छा तरीका हो सकता है. यह खास तौर पर उन संसाधनों के लिए ज़रूरी है जो ETag का इस्तेमाल करते हैं. ऐसा इसलिए, क्योंकि संसाधन को अपडेट करने के लिए, आपको If-Match एचटीटीपी हेडर में मौजूदा ETag वैल्यू देनी होगी. डेटा मिलने के बाद, उन वैल्यू में बदलाव किया जा सकता है जिन्हें आपको बदलना है. इसके बाद, पैच अनुरोध के साथ बदली गई वैल्यू को वापस भेजा जा सकता है. यहां एक उदाहरण दिया गया है, जिसमें यह माना गया है कि डेमो रिसॉर्स में ETag का इस्तेमाल किया गया है:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

यह जवाब का कुछ हिस्सा है:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

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

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

सर्वर, 200 OK एचटीटीपी स्टेटस कोड और अपडेट किए गए संसाधन का कुछ हिस्सा दिखाकर जवाब देता है:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

सीधे तौर पर पैच का अनुरोध बनाना

कुछ पैच अनुरोधों के लिए, आपको उन्हें उस डेटा के आधार पर बनाना होगा जिसे आपने पहले वापस पाया था. उदाहरण के लिए, अगर आपको किसी ऐरे में कोई आइटम जोड़ना है और आपको ऐरे के किसी भी मौजूदा एलिमेंट को नहीं हटाना है, तो आपको पहले मौजूदा डेटा लेना होगा. इसी तरह, अगर कोई एपीआई ETag का इस्तेमाल करता है, तो आपको अपने अनुरोध के साथ पिछली ETag वैल्यू भेजनी होगी, ताकि संसाधन को अपडेट किया जा सके.

ध्यान दें: ETag के इस्तेमाल के दौरान, पैच को लागू करने के लिए "If-Match: *" एचटीटीपी हेडर का इस्तेमाल किया जा सकता है.  ऐसा करने पर, आपको डेटा को लिखने से पहले उसे पढ़ने की ज़रूरत नहीं पड़ेगी.

हालांकि, अन्य स्थितियों में, मौजूदा डेटा को पहले वापस लाए बिना, सीधे पैच अनुरोध बनाया जा सकता है. उदाहरण के लिए, आसानी से पैच अनुरोध सेट अप किया जा सकता है, जो किसी फ़ील्ड को नई वैल्यू पर अपडेट करता है या नया फ़ील्ड जोड़ता है. उदाहरण के लिए:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

इस अनुरोध के साथ, अगर टिप्पणी फ़ील्ड में कोई मौजूदा वैल्यू है, तो नई वैल्यू उसे ओवरराइट कर देती है. अगर कोई मौजूदा वैल्यू नहीं है, तो नई वैल्यू सेट हो जाती है. इसी तरह, अगर वॉल्यूम की कोई विशेषता मौजूद थी, तो उसकी वैल्यू को ओवरराइट कर दिया जाता है. अगर नहीं, तो उसे बनाया जाता है. अगर सटीक जानकारी वाला फ़ील्ड सेट है, तो उसे हटा दिया जाता है.

पैच के जवाब को मैनेज करना

मान्य पैच अनुरोध को प्रोसेस करने के बाद, एपीआई बदले गए संसाधन के पूरे रेप्रज़ेंटेशन के साथ-साथ 200 OK एचटीटीपी रिस्पॉन्स कोड दिखाता है. अगर एपीआई में ETag का इस्तेमाल किया जाता है, तो सर्वर, पैच अनुरोध को प्रोसेस करने के बाद ETag की वैल्यू अपडेट करता है. यह ठीक वैसे ही होता है जैसे PUT के साथ होता है.

पैच अनुरोध, रिसॉर्स का पूरा रिप्रज़ेंटेशन दिखाता है. हालांकि, अगर fields पैरामीटर का इस्तेमाल करके, दिखाए जाने वाले डेटा की संख्या कम की जाती है, तो ऐसा नहीं होता.

अगर पैच अनुरोध की वजह से, संसाधन की नई स्थिति सिंटैक्टिक या सेमेटिक तौर पर अमान्य होती है, तो सर्वर 400 Bad Request या 422 Unprocessable Entity एचटीटीपी स्टेटस कोड दिखाता है. साथ ही, संसाधन की स्थिति में कोई बदलाव नहीं होता. उदाहरण के लिए, अगर किसी ज़रूरी फ़ील्ड की वैल्यू मिटाने की कोशिश की जाती है, तो सर्वर गड़बड़ी का मैसेज दिखाता है.

PATCH एचटीटीपी वर्ब काम न करने पर, वैकल्पिक नोटेशन

अगर आपका फ़ायरवॉल, एचटीटीपी PATCH रिक्वेस्ट की अनुमति नहीं देता है, तो एचटीटीपी POST रिक्वेस्ट करें और बदले गए हेडर को PATCH पर सेट करें, जैसा कि यहां दिखाया गया है:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

पैच और अपडेट में अंतर

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

इसलिए, पैच का इस्तेमाल करना ज़्यादा सुरक्षित है. आपको सिर्फ़ उन फ़ील्ड के लिए डेटा देना होता है जिन्हें बदलना है. जिन फ़ील्ड को छोड़ा जाता है उन्हें मिटाया नहीं जाता. इस नियम का अपवाद सिर्फ़ दोहराए जाने वाले एलिमेंट या ऐरे के लिए है: अगर आपने सभी एलिमेंट या ऐरे को शामिल नहीं किया है, तो वे वैसे ही बने रहेंगे; अगर आपने इनमें से कोई एलिमेंट या ऐरे शामिल किया है, तो पूरा सेट आपके दिए गए सेट से बदल जाएगा.

खास जानकारी

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

ऐसी स्थितियों के उदाहरण जिनमें आपको एक साथ कई फ़ाइलें अपलोड करनी होंगी:

• बड़ी संख्या में फ़ाइलों का मेटाडेटा हासिल करना.
• मेटाडेटा या प्रॉपर्टी को एक साथ अपडेट करना.
• बड़ी संख्या में फ़ाइलों की अनुमतियां बदलना. जैसे, नया उपयोगकर्ता या ग्रुप जोड़ना.
• पहली बार या लंबे समय तक ऑफ़लाइन रहने के बाद, लोकल क्लाइंट डेटा को सिंक करना.

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

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

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

अन्य पाबंदियों में ये शामिल हैं:

• 100 से ज़्यादा कॉल वाले बैच अनुरोधों की वजह से गड़बड़ी हो सकती है.
• हर इनर रिक्वेस्ट के लिए, यूआरएल की लंबाई 8,000 वर्णों से ज़्यादा नहीं होनी चाहिए.
• Google Drive में, मीडिया को एक साथ अपलोड या डाउनलोड करने या फ़ाइलों को एक्सपोर्ट करने की सुविधा उपलब्ध नहीं है.

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

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

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

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

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

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

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

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

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

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

एक साथ कई अनुरोध करने के लिए

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

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

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

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

उदाहरण

इस उदाहरण में, Google Drive API के साथ एक साथ कई फ़ाइलें अपलोड करने का तरीका बताया गया है.

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

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963


--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8

{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8

{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

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

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

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT


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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "12218244892818058021i"
}

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "04109509152946699072k"
}

--batch_6VIxXCQbJoQ_AATxy_GgFUk--