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

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

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

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

उदाहरण	असर
title	अनुरोध किए गए संसाधन का title फ़ील्ड दिखाता है.
author/uri	अनुरोध किए गए संसाधन में author ऑब्जेक्ट का uri सब-फ़ील्ड दिखाता है.
links/*/href	links के चाइल्ड ऑब्जेक्ट के href फ़ील्ड को दिखाता है.

उप-चुनावों का इस्तेमाल करके, खास फ़ील्ड के सिर्फ़ कुछ हिस्सों के लिए अनुरोध करें.

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

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