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

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

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

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

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

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 ऑब्जेक्ट में नेस्ट किया जाता है, इसलिए 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`	आइटम कलेक्शन में मौजूद हर एलिमेंट के लिए, `pagemap` के सभी ऑब्जेक्ट के सिर्फ़ `title` फ़ील्ड (अगर मौजूद हो) दिखाता है.

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

उदाहरण	असर
`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 को लागू करने वाले पुराने वर्शन से अलग (और आसान) हैं.

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

उदाहरण

इस उदाहरण में, पैच के लिए एक सामान्य अनुरोध दिखाया गया है. इसमें सामान्य (काल्पनिक) "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 देखें.

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

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

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

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

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

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

अगर आपका फ़ायरवॉल एचटीटीपी 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 API कॉल शामिल होते हैं. उस मुख्य एचटीटीपी अनुरोध में, हर हिस्से में एक नेस्ट किया गया एचटीटीपी अनुरोध होता है.

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