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

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

अपवाद: "डेटा" का इस्तेमाल करने वाले एपीआई से मिले जवाबों के लिए रैपर, जहां जवाब data: { ... } जैसा दिखने वाले data ऑब्जेक्ट में नेस्ट होता है, "data" को शामिल न करें fields स्पेसिफ़िकेशन में दी गई है. 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`	आइटम के कलेक्शन में मौजूद हर एलिमेंट के लिए, उन सभी ऑब्जेक्ट का सिर्फ़ `title` फ़ील्ड दिखाता है जो `pagemap` के चाइल्ड हैं.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है यहां संसाधन के लेवल के कुछ उदाहरण दिए गए हैं:

उदाहरण	असर
`title`	अनुरोध किए गए संसाधन का `title` फ़ील्ड दिखाता है.
`author/uri`	अनुरोध किए गए संसाधन में `author` ऑब्जेक्ट का `uri` सब-फ़ील्ड दिखाता है.
`links/*/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 फ़ॉर्मैट के पुराने डेटा से अलग (और आसान) हैं.

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

उदाहरण

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

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

पढ़ने-में बदलाव करने के साइकल में पैच का इस्तेमाल करना

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

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

बैच रिक्वेस्ट का फ़ॉर्मैट

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

हर हिस्सा, अपने 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. ये फ़ील्ड शायद वही फ़ील्ड न हों जो आपने ज़रूरत. अगर आपको अन्य फ़ील्ड वापस करने हैं, तो देखें फ़ाइल के लिए खास फ़ील्ड दिखाएं.