प्रदर्शन सुझाव

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

gzip की मदद से कंप्रेस करना

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

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

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