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