परफ़ॉर्मेंस से जुड़ी सलाह

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

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

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

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

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

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

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

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

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

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

अधूरे जवाब का अनुरोध

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

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

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

उदाहरण

इस उदाहरण में, "Demo" नाम के फ़िक्शनल (काल्पनिक) एपीआई के साथ 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 जैसे फ़ील्ड से जुड़े खास जानकारी वाले डेटा ऑब्जेक्ट को शामिल करने से गड़बड़ी होती है. इसके बजाय, सिर्फ़ fields जैसी खास जानकारी का इस्तेमाल करें. जैसे, a/b.

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

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

• ज़रूरत पड़ने पर, फ़ील्ड चुनने के लिए वाइल्डकार्ड का इस्तेमाल करें.

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

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

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

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

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

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

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

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

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

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

सब-सिलेक्शन का इस्तेमाल करके, सिर्फ़ खास फ़ील्ड के कुछ हिस्सों का अनुरोध करें.

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

उदाहरण	प्रभाव
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) का इस्तेमाल करते हैं, उन पैरामीटर का इस्तेमाल करके हर क्वेरी के नतीजों को कम करें, ताकि उन्हें मैनेज किया जा सके. ऐसा न करने पर, अधूरे जवाब से मिलने वाले परफ़ॉर्मेंस के फ़ायदे नहीं मिल पाएंगे.

पैच (कुछ हिस्सों के लिए अपडेट)

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

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

उदाहरण

इस उदाहरण में, "Demo" नाम के फ़िक्शनल (काल्पनिक) एपीआई संसाधन के सिर्फ़ टाइटल को अपडेट करने के लिए, पैच का एक सामान्य अनुरोध दिखाया गया है. संसाधन में टिप्पणी, विशेषताओं का सेट, स्टेटस, और कई अन्य फ़ील्ड भी हैं. हालांकि, इस अनुरोध में सिर्फ़ 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 देखें.

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

रीड-मॉडिफ़ाई-राइट साइकल में पैच का इस्तेमाल करना

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

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" g>"Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

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

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

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

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