इस दस्तावेज़ में कुछ ऐसी तकनीकों के बारे में बताया गया है जिनका इस्तेमाल करके, अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. कुछ मामलों में, अन्य एपीआई या सामान्य एपीआई के उदाहरणों का इस्तेमाल, दिखाए गए आइडिया को दिखाने के लिए किया जाता है. हालांकि, Google Wallet API पर भी यही सिद्धांत लागू होते हैं.
gzip की मदद से कंप्रेस करना
हर अनुरोध के लिए ज़रूरी बैंडविड्थ को कम करने का एक आसान और आसान तरीका, gzip संपीड़न को चालू करना है. हालांकि, नतीजों को अनकंप्रेस करने के लिए सीपीयू के इस्तेमाल में ज़्यादा समय लगता है, लेकिन आम तौर पर नेटवर्क की लागत के साथ तालमेल बिठाना काफ़ी फ़ायदेमंद होता है.
gzip की मदद से कोड में बदले गए जवाब पाने के लिए आपको दो काम करने होंगे: Accept-Encoding
हेडर सेट करें और अपने उपयोगकर्ता एजेंट में बदलाव करके gzip
स्ट्रिंग शामिल करें. यहां gzip कंप्रेशन को चालू करने के लिए, सही तरीके से बनाए गए एचटीटीपी हेडर का उदाहरण दिया गया है:
Accept-Encoding: gzip User-Agent: my program (gzip)
आंशिक संसाधनों के साथ काम करना
एपीआई कॉल की परफ़ॉर्मेंस को बेहतर बनाने का एक और तरीका यह है कि डेटा का सिर्फ़ वही हिस्सा भेजें और पाएं जिसमें आपकी दिलचस्पी है. इससे आपका ऐप्लिकेशन ग़ैर-ज़रूरी फ़ील्ड को ट्रांसफ़र, पार्स, और स्टोर नहीं कर पाता, ताकि वह नेटवर्क, सीपीयू, और मेमोरी जैसे संसाधनों का बेहतर तरीके से इस्तेमाल कर सके.
अधूरे अनुरोध दो तरह के होते हैं:
- अधूरे जवाब: वह अनुरोध जिसमें आप तय करते हैं कि जवाब में किन फ़ील्ड को शामिल करना है (
fields
अनुरोध पैरामीटर का इस्तेमाल करें). - पैच: अपडेट करने का अनुरोध, जिसमें सिर्फ़ वे फ़ील्ड भेजे जाते हैं जिनमें आपको बदलाव करना है. इसके लिए,
PATCH
एचटीटीपी क्रिया का इस्तेमाल करें.
कुछ हद तक अनुरोध करने से जुड़ी ज़्यादा जानकारी नीचे दिए गए सेक्शन में दी गई है.
अधूरे जवाब
डिफ़ॉल्ट रूप से, सर्वर अनुरोधों को प्रोसेस करने के बाद संसाधन का पूरा ब्यौरा वापस भेजता है. बेहतर परफ़ॉर्मेंस के लिए, सर्वर से कहें कि वह सिर्फ़ वे फ़ील्ड भेजे जिनकी आपको वाकई ज़रूरत है और पार्शियल रिस्पॉन्स पाएं.
अगर आपको अधूरा जवाब देना है, तो fields
अनुरोध पैरामीटर का इस्तेमाल करके, उन फ़ील्ड की जानकारी दें जिन्हें आपको लौटाना है. इस पैरामीटर का इस्तेमाल, रिस्पॉन्स का डेटा दिखाने वाले किसी भी अनुरोध के साथ किया जा सकता है.
ध्यान दें कि 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
) के लिए क्वेरी पैरामीटर के साथ काम करते हैं, उन पैरामीटर का इस्तेमाल करें, ताकि हर क्वेरी के नतीजों को मैनेज किए जा सकने वाले साइज़ तक कम किया जा सके. ऐसा न करने पर, हो सकता है कि अधूरे जवाब देने पर परफ़ॉर्मेंस अच्छा न हो.
पैच (आंशिक अपडेट)
संसाधनों में बदलाव करते समय बेवजह का डेटा भेजने से भी बचा जा सकता है. सिर्फ़ उन फ़ील्ड के लिए अपडेट किया गया डेटा भेजने के लिए जिन्हें बदला जा रहा है, एचटीटीपी PATCH
क्रिया का इस्तेमाल करें. इस दस्तावेज़ में बताए गए पैच सिमैंटिक, कुछ हद तक अपडेट करने वाले GData को लागू करने वाले पुराने वर्शन से अलग (और आसान) हैं.
नीचे दिए गए उदाहरण में यह दिखाया गया है कि पैच का इस्तेमाल करने से, उस डेटा को कैसे कम किया जा सकता है जिसे छोटा अपडेट करने के लिए भेजना ज़रूरी है.
उदाहरण
इस उदाहरण में, एक सामान्य पैच अनुरोध दिखाया गया है. इसमें सिर्फ़ सामान्य (काल्पनिक) "डेमो" एपीआई संसाधन का टाइटल अपडेट किया गया है. संसाधन में एक टिप्पणी, विशेषताओं का सेट, स्थिति, और कई अन्य फ़ील्ड भी होते हैं. हालांकि, यह अनुरोध सिर्फ़ title
फ़ील्ड को भेजता है, क्योंकि सिर्फ़ उसी फ़ील्ड में बदलाव किया जा रहा है:
PATCH https://www.googleapis.com/demo/v1/324 Authorization: Bearer your_auth_token Content-Type: application/json { "title": "New title" }
जवाब:
200 OK
{ "title": "New title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }
सर्वर, अपडेट किए गए रिसॉर्स की पूरी जानकारी के साथ 200 OK
स्टेटस कोड दिखाता है. पैच अनुरोध में सिर्फ़ title
फ़ील्ड शामिल किया गया था, इसलिए सिर्फ़ यही वैल्यू पहले से अलग है.
ध्यान दें: अगर पैच के साथ पार्शियल रिस्पॉन्स fields
पैरामीटर इस्तेमाल किया जाता है, तो अपडेट करने के अनुरोधों की परफ़ॉर्मेंस को और बेहतर बनाया जा सकता है. पैच का अनुरोध करने से, सिर्फ़ अनुरोध का साइज़ छोटा होता है. अधूरा जवाब, रिस्पॉन्स का साइज़ कम कर देता है. इसलिए, दोनों तरफ़ से भेजे जाने वाले डेटा को कम करने के लिए, fields
पैरामीटर वाले पैच अनुरोध का इस्तेमाल करें.
पैच अनुरोध के सिमैंटिक
पैच अनुरोध के मुख्य हिस्से में सिर्फ़ वे संसाधन फ़ील्ड शामिल होते हैं जिनमें आपको बदलाव करना है. जब किसी फ़ील्ड के बारे में बताया जाता है, तो आपको उस फ़ील्ड में शामिल पैरंट ऑब्जेक्ट को भी शामिल करना होता है. ठीक उसी तरह, जिस तरह इन क्लोज़िंग पैरंट ऑब्जेक्ट को आंशिक रिस्पॉन्स के साथ दिखाया जाता है. आपके भेजे गए बदले हुए डेटा को, पैरंट ऑब्जेक्ट के डेटा में मर्ज कर दिया जाता है.
- जोड़ना: अगर कोई फ़ील्ड पहले से मौजूद नहीं है, तो उसे जोड़ने के लिए नया फ़ील्ड और उसकी वैल्यू डालें.
- बदलाव करें: किसी मौजूदा फ़ील्ड की वैल्यू बदलने के लिए, फ़ील्ड की जानकारी दें और उसे नई वैल्यू पर सेट करें.
- मिटाना: किसी फ़ील्ड को मिटाने के लिए, उसकी जानकारी दें और उसे
null
पर सेट करें. उदाहरण के लिए,"comment": null
. किसी पूरे ऑब्जेक्ट कोnull
पर सेट करके उसे मिटाया भी जा सकता है. ऐसा तब किया जा सकता है, जब उसमें बदलाव किया जा सकता हो. अगर आप Java API क्लाइंट लाइब्रेरी का इस्तेमाल कर रहे हैं, तो इसके बजायData.NULL_STRING
का इस्तेमाल करें. ज़्यादा जानकारी के लिए, JSON null देखें.
अरे के बारे में जानकारी: अरे वाले पैच अनुरोध, मौजूदा कलेक्शन को आपके दिए गए कलेक्शन से बदल देते हैं. किसी कलेक्शन में मौजूद छोटे-छोटे आइटम में बदलाव नहीं किया जा सकता, उन्हें जोड़ा या मिटाया नहीं जा सकता.
पढ़ने-बदलने-लिखने के साइकल में पैच का इस्तेमाल करना
आपको जिस डेटा में बदलाव करना है उसके साथ आंशिक जवाब पाने से शुरुआत करना फ़ायदेमंद हो सकता है. यह खास तौर पर, ETag का इस्तेमाल करने वाले संसाधनों के लिए ज़रूरी है, क्योंकि संसाधन को अपडेट करने के लिए, आपको If-Match
एचटीटीपी हेडर में मौजूदा ETag वैल्यू देनी होगी. डेटा मिलने के बाद, उन वैल्यू में बदलाव किया जा सकता है जिन्हें बदलना है. साथ ही, बदलाव किए गए पार्शियल प्रज़ेंटेशन को पैच अनुरोध के साथ वापस भेजा जा सकता है. यहां एक उदाहरण दिया गया है, जिसमें माना जाता है कि डेमो रिसॉर्स, ETag का इस्तेमाल करता है:
GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token
यह आंशिक जवाब है:
200 OK
{ "etag": "ETagString" "title": "New title" "comment": "First comment.", "characteristics": { "length": "short", "level": "5", "followers": ["Jo", "Will"], } }
नीचे दिया गया पैच के लिए अनुरोध, इस रिस्पॉन्स पर आधारित है. जैसा कि नीचे दिखाया गया है, यह पैच रिस्पॉन्स में मिले डेटा को सीमित करने के लिए, fields
पैरामीटर का भी इस्तेमाल करता है:
PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json If-Match: "ETagString"
{ "etag": "ETagString" "title": "", /* Clear the value of the title by setting it to the empty string. */ "comment": null, /* Delete the comment by replacing its value with null. */ "characteristics": { "length": "short", "level": "10", /* Modify the level value. */ "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */ "accuracy": "high" /* Add a new characteristic. */ }, }
इसके बाद, सर्वर 200 OK एचटीटीपी स्टेटस कोड के साथ जवाब देता है और अपडेट किए गए रिसॉर्स को कुछ हद तक दिखाता है:
200 OK
{ "etag": "newETagString" "title": "", /* Title is cleared; deleted comment field is missing. */ "characteristics": { "length": "short", "level": "10", /* Value is updated.*/ "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */ "accuracy": "high" /* New characteristic is present. */ } }
सीधे पैच अनुरोध तैयार करना
कुछ पैच अनुरोधों के लिए, आपको उन्हें पहले वापस लिए गए डेटा के आधार पर बनाना होगा. उदाहरण के लिए, अगर आपको किसी आइटम को अरे में जोड़ना है और ऐरे एलिमेंट में मौजूद किसी भी एलिमेंट को नहीं गंवाना है, तो पहले आपको मौजूदा डेटा लाना होगा. इसी तरह, अगर कोई एपीआई ETag का इस्तेमाल करता है, तो रिसॉर्स को अपडेट करने के लिए आपको अपने अनुरोध के साथ पिछली ETag वैल्यू भेजनी होगी.
ध्यान दें: जब ETag का इस्तेमाल किया जा रहा हो, तब किसी पैच को ज़बरदस्ती दिखाने के लिए "If-Match: *"
एचटीटीपी हेडर का इस्तेमाल किया जा सकता है. अगर ऐसा किया जाता है, तो आपको ईमेल लिखने से पहले, पढ़ने की ज़रूरत नहीं है.
हालांकि, अन्य स्थितियों के लिए, मौजूदा डेटा को वापस लाए बिना, सीधे पैच अनुरोध बनाया जा सकता है. उदाहरण के लिए, आसानी से पैच अनुरोध सेट अप किया जा सकता है, जो किसी फ़ील्ड को नई वैल्यू पर अपडेट करता है या नया फ़ील्ड जोड़ता है. उदाहरण के लिए:
PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json { "comment": "A new comment", "characteristics": { "volume": "loud", "accuracy": null } }
इस अनुरोध में, अगर टिप्पणी फ़ील्ड में कोई वैल्यू मौजूद है, तो नई वैल्यू उसे ओवरराइट कर देती है. ऐसा न होने पर, वह नई वैल्यू पर सेट हो जाती है. इसी तरह, अगर वॉल्यूम की विशेषता थी, तो उसकी वैल्यू बदल दी जाती है. अगर ऐसा नहीं है, तो वैल्यू बना दी जाती है. अगर सटीक जानकारी वाले फ़ील्ड को सेट किया जाता है, तो उसे हटा दिया जाता है.
पैच का रिस्पॉन्स मैनेज करना
पैच के मान्य अनुरोध को प्रोसेस करने के बाद, एपीआई बदले गए संसाधन की पूरी जानकारी के साथ 200 OK
एचटीटीपी रिस्पॉन्स कोड दिखाता है. अगर एपीआई, ETag का इस्तेमाल करता है, तो सर्वर PUT
के साथ भी ठीक तरह से ETag वैल्यू को अपडेट करता है. ऐसा तब होता है, जब यह पैच के अनुरोध को प्रोसेस करता है.
पैच अनुरोध की मदद से, पूरा संसाधन दिखाया जाता है. ऐसा तब तक होता है, जब तक fields
पैरामीटर का इस्तेमाल करके, लौटाए जाने वाले डेटा की मात्रा को कम नहीं किया जाता.
अगर पैच अनुरोध, संसाधन की ऐसी नई स्थिति देता है जो वाक्य की या शब्दों के हिसाब से गलत है, तो सर्वर 400 Bad Request
या 422 Unprocessable Entity
एचटीटीपी स्टेटस कोड दिखाता है. हालांकि, संसाधन की स्थिति में कोई बदलाव नहीं होता. उदाहरण के लिए, अगर किसी ज़रूरी फ़ील्ड की वैल्यू को मिटाने की कोशिश की जाती है, तो सर्वर कोई गड़बड़ी दिखाता है.
PATCH HTTP क्रिया समर्थित न होने पर वैकल्पिक संकेतन
अगर आपका फ़ायरवॉल एचटीटीपी PATCH
अनुरोधों को अनुमति नहीं देता है, तो एचटीटीपी POST
अनुरोध करें और ओवरराइड हेडर को PATCH
पर सेट करें, जैसा कि यहां दिखाया गया है:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
पैच और अपडेट में अंतर
असल में, एचटीटीपी PUT
वर्ब का इस्तेमाल करने वाले अपडेट के अनुरोध के लिए डेटा भेजने पर, आपको सिर्फ़ ज़रूरी या वैकल्पिक फ़ील्ड भेजने होंगे. अगर सर्वर से सेट की गई फ़ील्ड के लिए वैल्यू भेजी जाती हैं, तो उन्हें अनदेखा कर दिया जाता है. हालांकि, यह तरीका कुछ हद तक अपडेट करने का एक और तरीका हो सकता है, लेकिन इस तरीके की कुछ सीमाएं हैं. एचटीटीपी PUT
वर्ब का इस्तेमाल करने वाले अपडेट में, ज़रूरी पैरामीटर उपलब्ध न कराने पर अनुरोध काम नहीं करता. साथ ही, वैकल्पिक पैरामीटर न देने पर, पहले से सेट किया गया डेटा मिटा दिया जाता है.
इस वजह से पैच का इस्तेमाल करना ज़्यादा सुरक्षित होता है. सिर्फ़ उन फ़ील्ड का डेटा उपलब्ध कराया जाता है जिन्हें बदलना है. हालांकि, जिन फ़ील्ड को हटाया जाता है उन्हें हटाया नहीं जाता. इस नियम का अपवाद सिर्फ़ दोहराए जाने वाले एलिमेंट या अरे के साथ होता है: अगर आप सभी को छोड़ देते हैं, तो वे वैसे ही रहते हैं जैसे वे हैं; अगर आप इनमें से कोई भी देते हैं, तो पूरे सेट को आपके दिए गए सेट से बदल दिया जाता है.
Google Wallet को एक साथ भेजे जाने वाले अनुरोध
Google Wallet API, एक साथ कई एपीआई कॉल के लिए बैच बनाने की सुविधा देता है. इससे क्लाइंट के कनेक्शन की संख्या कम हो जाती है. बैच अनुरोध और उसके रिस्पॉन्स के स्ट्रक्चर के बारे में ज़्यादा जानने के लिए, बैच की जानकारी देखें.
नीचे दिए गए सैंपल कोड से, एक साथ कई अनुरोध भेजने के बारे में जानकारी मिलती है. Java और PHP के उदाहरण, क्लास और ऑब्जेक्ट बनाने को आसान बनाने के लिए Google Wallet लाइब्रेरी का इस्तेमाल करते हैं.
Java
Java में इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे सभी कोड सैंपल देखें.
/** * Batch create Google Wallet objects from an existing class. * * @param issuerId The issuer ID being used for this request. * @param classSuffix Developer-defined unique ID for this pass class. */ public void batchCreateObjects(String issuerId, String classSuffix) throws IOException { // Create the batch request client BatchRequest batch = service.batch(new HttpCredentialsAdapter(credentials)); // The callback will be invoked for each request in the batch JsonBatchCallback<OfferObject> callback = new JsonBatchCallback<OfferObject>() { // Invoked if the request was successful public void onSuccess(OfferObject response, HttpHeaders responseHeaders) { System.out.println("Batch insert response"); System.out.println(response.toString()); } // Invoked if the request failed public void onFailure(GoogleJsonError e, HttpHeaders responseHeaders) { System.out.println("Error Message: " + e.getMessage()); } }; // Example: Generate three new pass objects for (int i = 0; i < 3; i++) { // Generate a random object suffix String objectSuffix = UUID.randomUUID().toString().replaceAll("[^\\w.-]", "_"); // See link below for more information on required properties // https://developers.google.com/wallet/retail/offers/rest/v1/offerobject OfferObject batchObject = new OfferObject() .setId(String.format("%s.%s", issuerId, objectSuffix)) .setClassId(String.format("%s.%s", issuerId, classSuffix)) .setState("ACTIVE") .setHeroImage( new Image() .setSourceUri( new ImageUri() .setUri( "https://farm4.staticflickr.com/3723/11177041115_6e6a3b6f49_o.jpg")) .setContentDescription( new LocalizedString() .setDefaultValue( new TranslatedString() .setLanguage("en-US") .setValue("Hero image description")))) .setTextModulesData( List.of( new TextModuleData() .setHeader("Text module header") .setBody("Text module body") .setId("TEXT_MODULE_ID"))) .setLinksModuleData( new LinksModuleData() .setUris( Arrays.asList( new Uri() .setUri("http://maps.google.com/") .setDescription("Link module URI description") .setId("LINK_MODULE_URI_ID"), new Uri() .setUri("tel:6505555555") .setDescription("Link module tel description") .setId("LINK_MODULE_TEL_ID")))) .setImageModulesData( List.of( new ImageModuleData() .setMainImage( new Image() .setSourceUri( new ImageUri() .setUri( "http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg")) .setContentDescription( new LocalizedString() .setDefaultValue( new TranslatedString() .setLanguage("en-US") .setValue("Image module description")))) .setId("IMAGE_MODULE_ID"))) .setBarcode(new Barcode().setType("QR_CODE").setValue("QR code value")) .setLocations( List.of( new LatLongPoint() .setLatitude(37.424015499999996) .setLongitude(-122.09259560000001))) .setValidTimeInterval( new TimeInterval() .setStart(new DateTime().setDate("2023-06-12T23:20:50.52Z")) .setEnd(new DateTime().setDate("2023-12-12T23:20:50.52Z"))); service.offerobject().insert(batchObject).queue(batch, callback); } // Invoke the batch API calls batch.execute(); }
PHP
PHP में अपना इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे सभी कोड सैंपल देखें.
/** * Batch create Google Wallet objects from an existing class. * * @param string $issuerId The issuer ID being used for this request. * @param string $classSuffix Developer-defined unique ID for the pass class. */ public function batchCreateObjects(string $issuerId, string $classSuffix) { // Update the client to enable batch requests $this->client->setUseBatch(true); $batch = $this->service->createBatch(); // Example: Generate three new pass objects for ($i = 0; $i < 3; $i++) { // Generate a random object suffix $objectSuffix = preg_replace('/[^\w.-]/i', '_', uniqid()); // See link below for more information on required properties // https://developers.google.com/wallet/retail/offers/rest/v1/offerobject $batchObject = new OfferObject([ 'id' => "{$issuerId}.{$objectSuffix}", 'classId' => "{$issuerId}.{$classSuffix}", 'state' => 'ACTIVE', 'heroImage' => new Image([ 'sourceUri' => new ImageUri([ 'uri' => 'https://farm4.staticflickr.com/3723/11177041115_6e6a3b6f49_o.jpg' ]), 'contentDescription' => new LocalizedString([ 'defaultValue' => new TranslatedString([ 'language' => 'en-US', 'value' => 'Hero image description' ]) ]) ]), 'textModulesData' => [ new TextModuleData([ 'header' => 'Text module header', 'body' => 'Text module body', 'id' => 'TEXT_MODULE_ID' ]) ], 'linksModuleData' => new LinksModuleData([ 'uris' => [ new Uri([ 'uri' => 'http://maps.google.com/', 'description' => 'Link module URI description', 'id' => 'LINK_MODULE_URI_ID' ]), new Uri([ 'uri' => 'tel:6505555555', 'description' => 'Link module tel description', 'id' => 'LINK_MODULE_TEL_ID' ]) ] ]), 'imageModulesData' => [ new ImageModuleData([ 'mainImage' => new Image([ 'sourceUri' => new ImageUri([ 'uri' => 'http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg' ]), 'contentDescription' => new LocalizedString([ 'defaultValue' => new TranslatedString([ 'language' => 'en-US', 'value' => 'Image module description' ]) ]) ]), 'id' => 'IMAGE_MODULE_ID' ]) ], 'barcode' => new Barcode([ 'type' => 'QR_CODE', 'value' => 'QR code value' ]), 'locations' => [ new LatLongPoint([ 'latitude' => 37.424015499999996, 'longitude' => -122.09259560000001 ]) ], 'validTimeInterval' => new TimeInterval([ 'start' => new DateTime([ 'date' => '2023-06-12T23:20:50.52Z' ]), 'end' => new DateTime([ 'date' => '2023-12-12T23:20:50.52Z' ]) ]) ]); $batch->add($this->service->offerobject->insert($batchObject)); } // Make the batch request $batchResponse = $batch->execute(); print "Batch insert response\n"; foreach ($batchResponse as $key => $value) { if ($value instanceof Google_Service_Exception) { print_r($value->getErrors()); continue; } print "{$value->getId()}\n"; } }
Python
Python में इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे सभी कोड सैंपल देखें.
def batch_create_objects(self, issuer_id: str, class_suffix: str): """Batch create Google Wallet objects from an existing class. The request body will be a multiline string. See below for information. https://cloud.google.com/compute/docs/api/how-tos/batch#example Args: issuer_id (str): The issuer ID being used for this request. class_suffix (str): Developer-defined unique ID for this pass class. """ batch = self.client.new_batch_http_request() # Example: Generate three new pass objects for _ in range(3): # Generate a random object suffix object_suffix = str(uuid.uuid4()).replace('[^\\w.-]', '_') # See link below for more information on required properties # https://developers.google.com/wallet/retail/offers/rest/v1/offerobject batch_object = { 'id': f'{issuer_id}.{object_suffix}', 'classId': f'{issuer_id}.{class_suffix}', 'state': 'ACTIVE', 'heroImage': { 'sourceUri': { 'uri': 'https://farm4.staticflickr.com/3723/11177041115_6e6a3b6f49_o.jpg' }, 'contentDescription': { 'defaultValue': { 'language': 'en-US', 'value': 'Hero image description' } } }, 'textModulesData': [{ 'header': 'Text module header', 'body': 'Text module body', 'id': 'TEXT_MODULE_ID' }], 'linksModuleData': { 'uris': [{ 'uri': 'http://maps.google.com/', 'description': 'Link module URI description', 'id': 'LINK_MODULE_URI_ID' }, { 'uri': 'tel:6505555555', 'description': 'Link module tel description', 'id': 'LINK_MODULE_TEL_ID' }] }, 'imageModulesData': [{ 'mainImage': { 'sourceUri': { 'uri': 'http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg' }, 'contentDescription': { 'defaultValue': { 'language': 'en-US', 'value': 'Image module description' } } }, 'id': 'IMAGE_MODULE_ID' }], 'barcode': { 'type': 'QR_CODE', 'value': 'QR code' }, 'locations': [{ 'latitude': 37.424015499999996, 'longitude': -122.09259560000001 }], 'validTimeInterval': { 'start': { 'date': '2023-06-12T23:20:50.52Z' }, 'end': { 'date': '2023-12-12T23:20:50.52Z' } } } batch.add(self.client.offerobject().insert(body=batch_object)) # Invoke the batch API calls response = batch.execute() print('Batch complete')
C#
C# में इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे सभी कोड सैंपल देखें.
/// <summary> /// Batch create Google Wallet objects from an existing class. /// </summary> /// <param name="issuerId">The issuer ID being used for this request.</param> /// <param name="classSuffix">Developer-defined unique ID for this pass class.</param> public async void BatchCreateObjects(string issuerId, string classSuffix) { // The request body will be a multiline string // See below for more information // https://cloud.google.com/compute/docs/api/how-tos/batch//example string data = ""; HttpClient httpClient = new HttpClient(); httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue( "Bearer", credentials.GetAccessTokenForRequestAsync().Result ); // Example: Generate three new pass objects for (int i = 0; i < 3; i++) { // Generate a random object suffix string objectSuffix = Regex.Replace(Guid.NewGuid().ToString(), "[^\\w.-]", "_"); // See link below for more information on required properties // https://developers.google.com/wallet/retail/offers/rest/v1/offerobject OfferObject batchObject = new OfferObject { Id = $"{issuerId}.{objectSuffix}", ClassId = $"{issuerId}.{classSuffix}", State = "ACTIVE", HeroImage = new Image { SourceUri = new ImageUri { Uri = "https://farm4.staticflickr.com/3723/11177041115_6e6a3b6f49_o.jpg" }, ContentDescription = new LocalizedString { DefaultValue = new TranslatedString { Language = "en-US", Value = "Hero image description" } } }, TextModulesData = new List<TextModuleData> { new TextModuleData { Header = "Text module header", Body = "Text module body", Id = "TEXT_MODULE_ID" } }, LinksModuleData = new LinksModuleData { Uris = new List<Google.Apis.Walletobjects.v1.Data.Uri> { new Google.Apis.Walletobjects.v1.Data.Uri { UriValue = "http://maps.google.com/", Description = "Link module URI description", Id = "LINK_MODULE_URI_ID" }, new Google.Apis.Walletobjects.v1.Data.Uri { UriValue = "tel:6505555555", Description = "Link module tel description", Id = "LINK_MODULE_TEL_ID" } } }, ImageModulesData = new List<ImageModuleData> { new ImageModuleData { MainImage = new Image { SourceUri = new ImageUri { Uri = "http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg" }, ContentDescription = new LocalizedString { DefaultValue = new TranslatedString { Language = "en-US", Value = "Image module description" } } }, Id = "IMAGE_MODULE_ID" } }, Barcode = new Barcode { Type = "QR_CODE", Value = "QR code" }, Locations = new List<LatLongPoint> { new LatLongPoint { Latitude = 37.424015499999996, Longitude = -122.09259560000001 } }, ValidTimeInterval = new TimeInterval { Start = new Google.Apis.Walletobjects.v1.Data.DateTime { Date = "2023-06-12T23:20:50.52Z" }, End = new Google.Apis.Walletobjects.v1.Data.DateTime { Date = "2023-12-12T23:20:50.52Z" } } }; data += "--batch_createobjectbatch\n"; data += "Content-Type: application/json\n\n"; data += "POST /walletobjects/v1/offerObject/\n\n"; data += JsonConvert.SerializeObject(batchObject) + "\n\n"; } data += "--batch_createobjectbatch--"; // Invoke the batch API calls HttpRequestMessage batchObjectRequest = new HttpRequestMessage( HttpMethod.Post, "https://walletobjects.googleapis.com/batch"); batchObjectRequest.Content = new StringContent(data); batchObjectRequest.Content.Headers.ContentType = new MediaTypeHeaderValue( "multipart/mixed"); // `boundary` is the delimiter between API calls in the batch request batchObjectRequest.Content.Headers.ContentType.Parameters.Add( new NameValueHeaderValue("boundary", "batch_createobjectbatch")); HttpResponseMessage batchObjectResponse = httpClient.Send( batchObjectRequest); string batchObjectContent = await batchObjectResponse .Content .ReadAsStringAsync(); Console.WriteLine("Batch insert response"); Console.WriteLine(batchObjectContent); }
Node.js
नोड में इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे सभी कोड सैंपल देखें.
/** * Batch create Google Wallet objects from an existing class. * * @param {string} issuerId The issuer ID being used for this request. * @param {string} classSuffix Developer-defined unique ID for this pass class. */ async batchCreateObjects(issuerId, classSuffix) { // See below for more information // https://cloud.google.com/compute/docs/api/how-tos/batch#example let data = ''; let batchObject; let objectSuffix; // Example: Generate three new pass objects for (let i = 0; i < 3; i++) { // Generate a random object suffix objectSuffix = uuidv4().replace('[^\w.-]', '_'); // See link below for more information on required properties // https://developers.google.com/wallet/retail/offers/rest/v1/offerobject batchObject = { 'id': `${issuerId}.${objectSuffix}`, 'classId': `${issuerId}.${classSuffix}`, 'state': 'ACTIVE', 'heroImage': { 'sourceUri': { 'uri': 'https://farm4.staticflickr.com/3723/11177041115_6e6a3b6f49_o.jpg' }, 'contentDescription': { 'defaultValue': { 'language': 'en-US', 'value': 'Hero image description' } } }, 'textModulesData': [ { 'header': 'Text module header', 'body': 'Text module body', 'id': 'TEXT_MODULE_ID' } ], 'linksModuleData': { 'uris': [ { 'uri': 'http://maps.google.com/', 'description': 'Link module URI description', 'id': 'LINK_MODULE_URI_ID' }, { 'uri': 'tel:6505555555', 'description': 'Link module tel description', 'id': 'LINK_MODULE_TEL_ID' } ] }, 'imageModulesData': [ { 'mainImage': { 'sourceUri': { 'uri': 'http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg' }, 'contentDescription': { 'defaultValue': { 'language': 'en-US', 'value': 'Image module description' } } }, 'id': 'IMAGE_MODULE_ID' } ], 'barcode': { 'type': 'QR_CODE', 'value': 'QR code' }, 'locations': [ { 'latitude': 37.424015499999996, 'longitude': -122.09259560000001 } ], 'validTimeInterval': { 'start': { 'date': '2023-06-12T23:20:50.52Z' }, 'end': { 'date': '2023-12-12T23:20:50.52Z' } } }; data += '--batch_createobjectbatch\n'; data += 'Content-Type: application/json\n\n'; data += 'POST /walletobjects/v1/offerObject\n\n'; data += JSON.stringify(batchObject) + '\n\n'; } data += '--batch_createobjectbatch--'; // Invoke the batch API calls let response = await this.client.context._options.auth.request({ url: 'https://walletobjects.googleapis.com/batch', method: 'POST', data: data, headers: { // `boundary` is the delimiter between API calls in the batch request 'Content-Type': 'multipart/mixed; boundary=batch_createobjectbatch' } }); console.log('Batch insert response'); console.log(response); }
शुरू करें
Go में अपना इंटिग्रेशन शुरू करने के लिए, GitHub पर हमारे पूरे कोड सैंपल देखें GitHub पर कोड सैंपल.
// Batch create Google Wallet objects from an existing class. func (d *demoOffer) batchCreateObjects(issuerId, classSuffix string) { data := "" for i := 0; i < 3; i++ { objectSuffix := strings.ReplaceAll(uuid.New().String(), "-", "_") offerObject := new(walletobjects.OfferObject) offerObject.Id = fmt.Sprintf("%s.%s", issuerId, objectSuffix) offerObject.ClassId = fmt.Sprintf("%s.%s", issuerId, classSuffix) offerObject.State = "ACTIVE" offerJson, _ := json.Marshal(offerObject) batchObject := fmt.Sprintf("%s", offerJson) data += "--batch_createobjectbatch\n" data += "Content-Type: application/json\n\n" data += "POST /walletobjects/v1/offerObject\n\n" data += batchObject + "\n\n" } data += "--batch_createobjectbatch--" res, err := d.credentials.Client(oauth2.NoContext).Post("https://walletobjects.googleapis.com/batch", "multipart/mixed; boundary=batch_createobjectbatch", bytes.NewBuffer([]byte(data))) if err != nil { fmt.Println(err) } else { b, _ := io.ReadAll(res.Body) fmt.Printf("Batch insert response:\n%s\n", b) } }