लौटाने के लिए फ़ील्ड चुनें

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

रिस्पॉन्स फ़ील्ड मास्क बनाकर, फ़ील्ड की सूची तय की जा सकती है. इसके बाद, $fields या fields पैरामीटर का इस्तेमाल करके या एचटीटीपी या जीआरपीसी हेडर X-Goog-FieldMask का इस्तेमाल करके, रिस्पॉन्स फ़ील्ड मास्क को किसी भी तरीके से पास किया जा सकता है.

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

रिस्पॉन्स फ़ील्ड मास्क तय करें

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

फ़ील्ड पाथ इस तरह बनाएं:

topLevelField[.secondLevelField][.thirdLevelField][...]

ध्यान दें: फ़ील्ड पाथ की सूची में कहीं भी स्पेस का इस्तेमाल न करें.

* के फ़ील्ड मास्क का इस्तेमाल करके, सभी फ़ील्ड के लिए अनुरोध किया जा सकता है.

चेतावनी: इस वाइल्डकार्ड फ़ील्ड मास्क का इस्तेमाल डेवलपमेंट में किया जा सकता है, लेकिन प्रोडक्शन में वाइल्डकार्ड (*) रिस्पॉन्स फ़ील्ड मास्क का इस्तेमाल न करें. यह कीमत उम्मीद से ज़्यादा हो सकती है, क्योंकि इस फ़ील्ड मास्क के ज़रिए ज़्यादा बेहतर सुविधाओं का अनुरोध किया जाता है. इससे रिस्पॉन्स मिलने में लगने वाला समय बढ़ जाता है. पक्का करें कि आपने सिर्फ़ उन फ़ील्ड का अनुरोध किया हो जो आपकी लागत को कम करने और जवाब देने में लगने वाले समय को कम करने के लिए ज़रूरी हैं.

फ़ील्ड मास्क बनाने के तरीके के बारे में ज़्यादा जानकारी के लिए, field_mask.proto देखें.

तय करें कि कौनसे फ़ील्ड मास्क का इस्तेमाल करना है

यह तय करने का तरीका यहां बताया गया है कि आपको किस फ़ील्ड मास्क का इस्तेमाल करना है:

1. `*` के फ़ील्ड मास्क का इस्तेमाल करके सभी फ़ील्ड का अनुरोध करें.
2. जवाब में फ़ील्ड की हैरारकी देखें और तय करें कि आपको कौनसे फ़ील्ड चाहिए.
3. फ़ील्ड हैरारकी का इस्तेमाल करके अपना फ़ील्ड मास्क बनाएं.

आस-पास खोज (नया) और टेक्स्ट सर्च (नए) के लिए, रिस्पॉन्स फ़ील्ड मास्क तय करना

आस-पास की खोज (नया) और Text Search (नया) जवाब के places फ़ील्ड में जगह से जुड़े ऑब्जेक्ट का कलेक्शन दिखाते हैं. इन एपीआई के लिए, places रिस्पॉन्स का टॉप लेवल फ़ील्ड है.

उदाहरण के लिए, किसी 'टेक्स्ट सर्च' (नया) से पूरा रिस्पॉन्स ऑब्जेक्ट देखने के लिए:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'

टेक्स्ट सर्च (नया) कॉल का पूरा रिस्पॉन्स ऑब्जेक्ट इस फ़ॉर्म में होता है:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "[phone]",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Spiced @ Barangaroo",
        "languageCode": "en"
      },      ...
    },
  ...
  ]
}

इसलिए, इन एपीआई के लिए फ़ील्ड मास्क को फ़ॉर्म में तय किया जाता है:

places[.secondLevelField][.thirdLevelField][...]

अगर आपको सिर्फ़ formattedAddress और displayName फ़ील्ड लौटाने हैं, तो अपने फ़ील्ड मास्क को इस पर सेट करें:

places.formattedAddress,places.displayName

displayName तय करने में displayName के text और language, दोनों फ़ील्ड शामिल होते हैं. अगर आपको सिर्फ़ text फ़ील्ड का इस्तेमाल करना है, तो फ़ील्ड मास्क को इस तरह सेट करें:

places.formattedAddress,places.displayName.text

जगह की जानकारी के लिए, रिस्पॉन्स फ़ील्ड मास्क तय करें (नया)

जगह की जानकारी से, फ़ॉर्म में सिर्फ़ एक जगह की जानकारी मिलती है:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

इसलिए, इस एपीआई के लिए फ़ील्ड मास्क तय किया जाता है. इसके लिए, उस 'जगह के ऑब्जेक्ट' के फ़ील्ड को तय किया जाता है जिसे आपको लौटाना है:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: formattedAddress,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

gRPC कॉल

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

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

फ़ील्ड पाथ का ध्यान रखना

जवाब में सिर्फ़ वे फ़ील्ड शामिल करें जिनकी आपको ज़रूरत है. सिर्फ़ उन फ़ील्ड को लौटाना जिनकी आपको ज़रूरत है:

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

ध्यान दें: जब रिस्पॉन्स मैसेज पार्स किया जाता है और जवाब वाले मैसेज के किसी फ़ील्ड में डिफ़ॉल्ट वैल्यू शामिल होती है, तो हो सकता है कि फ़ील्ड को रिस्पॉन्स फ़ील्ड से न हटाया जाए, भले ही आपने उसे रिस्पॉन्स फ़ील्ड मास्क में डाला हो. ज़्यादा जानकारी के लिए, भाषा गाइड (प्रोटो3) देखें.