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

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

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

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

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

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

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

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

अधूरे जवाब

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

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