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

gzip का उपयोग करके संपीड़न

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

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

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

आंशिक संसाधनों के साथ काम करना

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

अधूरे जवाब

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

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