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

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

gzip का उपयोग करके संपीड़न

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

gzip-कोड में बदला गया जवाब पाने के लिए आपको दो काम करने होंगे: एक Accept-Encoding हेडर सेट करें और gzip स्ट्रिंग को शामिल करने के लिए अपने उपयोगकर्ता एजेंट में बदलाव करें. यहां gzip कंप्रेशन को चालू करने के लिए सही तरीके से बनाए गए एचटीटीपी हेडर का एक उदाहरण दिया गया है:

Accept-Encoding: gzip
User-Agent: my program (gzip)

आंशिक संसाधनों के साथ काम करना

एपीआई कॉल की परफ़ॉर्मेंस को बेहतर बनाने का एक और तरीका यह है कि आप अपनी पसंद का डेटा ही भेजें और पाएं. इससे आपका ऐप्लिकेशन गैर-ज़रूरी फ़ील्ड को ट्रांसफ़र, पार्स, और सेव नहीं कर पाता. साथ ही, नेटवर्क, सीपीयू, और मेमोरी जैसे संसाधनों का बेहतर तरीके से इस्तेमाल कर पाता है.

आंशिक अनुरोध दो तरह के होते हैं:

  • अधूरा जवाब: वह अनुरोध जिसमें यह बताया जाता है कि रिस्पॉन्स में कौनसे फ़ील्ड शामिल करने हैं. इसके लिए, fields अनुरोध के पैरामीटर का इस्तेमाल करें.
  • पैच: अपडेट करने का अनुरोध, जिसमें सिर्फ़ वे फ़ील्ड भेजे जाते हैं जिन्हें बदलना है. इसके लिए, PATCH एचटीटीपी कार्रवाई का इस्तेमाल करें.

आंशिक अनुरोध करने के बारे में ज़्यादा जानकारी नीचे दिए गए सेक्शन में दी गई है.

अधूरे जवाब

डिफ़ॉल्ट रूप से, अनुरोधों को प्रोसेस करने के बाद सर्वर किसी संसाधन को पूरी तरह से दिखाने का अनुरोध करता है. बेहतर परफ़ॉर्मेंस के लिए, सर्वर से सिर्फ़ उन फ़ील्ड को भेजने के लिए कहा जा सकता है जिनकी आपको वाकई ज़रूरत है. साथ ही, उन्हें आंशिक जवाब भी दें.

अधूरे जवाब का अनुरोध करने के लिए, fields अनुरोध पैरामीटर का इस्तेमाल करके वे फ़ील्ड बताएं जिन्हें आपको लौटाना है. इस पैरामीटर का इस्तेमाल, ऐसे किसी भी अनुरोध के साथ किया जा सकता है जो रिस्पॉन्स डेटा दिखाता है.

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

  • एक से ज़्यादा फ़ील्ड चुनने के लिए, कॉमा लगाकर अलग की गई सूची का इस्तेमाल करें.
  • फ़ील्ड a में नेस्ट किए गए b फ़ील्ड को चुनने के लिए, a/b का इस्तेमाल करें; b में नेस्ट किए गए c फ़ील्ड को चुनने के लिए, a/b/c का इस्तेमाल करें.

    अपवाद: "डेटा" का इस्तेमाल करने वाले एपीआई से मिले जवाबों के लिए रैपर, जहां जवाब data: { ... } जैसा दिखने वाले data ऑब्जेक्ट में नेस्ट होता है, "data" को शामिल न करें fields स्पेसिफ़िकेशन में दी गई है. 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 आइटम के कलेक्शन में मौजूद हर एलिमेंट के लिए, उन सभी ऑब्जेक्ट का सिर्फ़ title फ़ील्ड दिखाता है जो pagemap के चाइल्ड हैं.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है यहां संसाधन के लेवल के कुछ उदाहरण दिए गए हैं:
उदाहरण असर
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 शून्य देखें.

अरे के बारे में जानकारी: अरे वाले पैच अनुरोध, मौजूदा कलेक्शन को आपके दिए गए अरे से बदल देते हैं. किसी कलेक्शन में मौजूद आइटम में छोटे-मोटे बदलाव करके, उन्हें जोड़ा या मिटाया नहीं जा सकता.

पढ़ने-में बदलाव करने के साइकल में पैच का इस्तेमाल करना

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

ध्यान दें: जब ई-टैग इस्तेमाल किया जा रहा हो, तब पैच लागू करने के लिए, "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 का इस्तेमाल किया जाता है, तो सर्वर पैच के अनुरोध को प्रोसेस करने पर, ETag की वैल्यू अपडेट करता है. यह काम, PUT की तरह ही होता है.

पैच अनुरोध पूरा संसाधन दिखाता है. ऐसा तब तक होता है, जब तक आप दिए गए डेटा की मात्रा को कम करने के लिए fields पैरामीटर का इस्तेमाल नहीं करते.

अगर पैच अनुरोध की वजह से, संसाधन की ऐसी नई स्थिति बनती है जो वाक्य या वाक्य के रूप में गलत है, तो सर्वर 400 Bad Request या 422 Unprocessable Entity एचटीटीपी स्टेटस कोड दिखाता है. हालांकि, संसाधन की स्थिति में कोई बदलाव नहीं होता. उदाहरण के लिए, अगर किसी ज़रूरी फ़ील्ड की वैल्यू मिटाने की कोशिश की जाती है, तो सर्वर गड़बड़ी दिखाता है.

वैकल्पिक नोटेशन, जब PATCH एचटीटीपी क्रिया काम नहीं करती है

अगर आपका फ़ायरवॉल, एचटीटीपी 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<LoyaltyObject> callback =
      new JsonBatchCallback<LoyaltyObject>() {
        // Invoked if the request was successful
        public void onSuccess(LoyaltyObject 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/loyalty-cards/rest/v1/loyaltyobject
    LoyaltyObject batchObject =
        new LoyaltyObject()
            .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)))
            .setAccountId("Account ID")
            .setAccountName("Account name")
            .setLoyaltyPoints(
                new LoyaltyPoints()
                    .setLabel("Points")
                    .setBalance(new LoyaltyPointsBalance().setInt(800)));

    service.loyaltyobject().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/loyalty-cards/rest/v1/loyaltyobject
    $batchObject = new LoyaltyObject([
      '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
        ])
      ],
      'accountId' => 'Account ID',
      'accountName' => 'Account name',
      'loyaltyPoints' => new LoyaltyPoints([
        'balance' => new LoyaltyPointsBalance([
          'int' => 800
        ])
      ])
    ]);

    $batch->add($this->service->loyaltyobject->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/loyalty-cards/rest/v1/loyaltyobject
        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
            }],
            'accountId': 'Account id',
            'accountName': 'Account name',
            'loyaltyPoints': {
                'label': 'Points',
                'balance': {
                    'int': 800
                }
            }
        }

        batch.add(self.client.loyaltyobject().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/loyalty-cards/rest/v1/loyaltyobject
    LoyaltyObject batchObject = new LoyaltyObject
    {
      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
        }
      },
      AccountId = "Account id",
      AccountName = "Account name",
      LoyaltyPoints = new LoyaltyPoints
      {
        Label = "Points",
        Balance = new LoyaltyPointsBalance
        {
          Int__ = 800
        }
      }
    };

    data += "--batch_createobjectbatch\n";
    data += "Content-Type: application/json\n\n";
    data += "POST /walletobjects/v1/loyaltyObject/\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/loyalty-cards/rest/v1/loyaltyobject
    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
        }
      ],
      'accountId': 'Account id',
      'accountName': 'Account name',
      'loyaltyPoints': {
        'label': 'Points',
        'balance': {
          'int': 800
        }
      }
    };

    data += '--batch_createobjectbatch\n';
    data += 'Content-Type: application/json\n\n';
    data += 'POST /walletobjects/v1/loyaltyObject\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 *demoLoyalty) batchCreateObjects(issuerId, classSuffix string) {
	data := ""
	for i := 0; i < 3; i++ {
		objectSuffix := strings.ReplaceAll(uuid.New().String(), "-", "_")

		loyaltyObject := new(walletobjects.LoyaltyObject)
		loyaltyObject.Id = fmt.Sprintf("%s.%s", issuerId, objectSuffix)
		loyaltyObject.ClassId = fmt.Sprintf("%s.%s", issuerId, classSuffix)
		loyaltyObject.AccountName = "Account name"
		loyaltyObject.AccountId = "Account id"
		loyaltyObject.State = "ACTIVE"

		loyaltyJson, _ := json.Marshal(loyaltyObject)
		batchObject := fmt.Sprintf("%s", loyaltyJson)

		data += "--batch_createobjectbatch\n"
		data += "Content-Type: application/json\n\n"
		data += "POST /walletobjects/v1/loyaltyObject\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)
	}
}