इस पेज का अनुवाद Cloud Translation API से किया गया है.

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

इस दस्तावेज़ में कुछ तकनीकों के बारे में बताया गया है. इनका इस्तेमाल करके, अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. कुछ मामलों में, दिए गए आइडिया को समझाने के लिए, अन्य एपीआई या सामान्य एपीआई के उदाहरणों का इस्तेमाल किया जाता है. हालांकि, यही सिद्धांत Google Drive API में भी लागू होते हैं.

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

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 की क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो क्लाइंट लाइब्रेरी का दस्तावेज़ देखें.

खास जानकारी

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

अनुरोध से खास फ़ील्ड दिखाना

डिफ़ॉल्ट रूप से, सर्वर इस्तेमाल किए गए तरीके के हिसाब से, संसाधन फ़ील्ड का डिफ़ॉल्ट सेट दिखाता है. उदाहरण के लिए, files.list मेथड से सिर्फ़ id, name, और mimeType दिख सकते हैं. ऐसा हो सकता है कि ये फ़ील्ड, आपके काम के न हों. अगर आपको अन्य फ़ील्ड दिखाने हैं, तो किसी फ़ाइल के लिए खास फ़ील्ड दिखाना लेख पढ़ें.