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