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

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

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

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

यूआरएल पैरामीटर के बारे में ज़्यादा जानकारी के लिए, सिस्टम पैरामीटर देखें.

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

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

फ़ील्ड पाथ बनाने और उसे तय करने के लिए, यह तरीका अपनाएं:

1. Routes API से, वे फ़ील्ड ढूंढें जिनमें आपको ज़रूरी जानकारी मिल सकती है. ज़्यादा जानकारी के लिए, फ़ील्ड रेफ़रंस देखें.
2. अपने काम के फ़ील्ड के पाथ तय करें और उनके लिए फ़ील्ड मास्क बनाएं: ज़्यादा जानकारी के लिए, यह तय करें कि आपको किस फ़ील्ड मास्क का इस्तेमाल करना है लेख पढ़ें.

3. अपने सभी ज़रूरी फ़ील्ड के लिए फ़ील्ड मास्क को जोड़ें. इसके लिए, फ़ील्ड मास्क को कॉमा लगाकर अलग करें. उदाहरण के लिए, रास्ते के हिस्से के लिए distanceMeters और रास्ते के हर चरण की अवधि का अनुरोध करने के लिए, दोनों को कॉमा लगाकर अलग करें. इनके बीच में कोई स्पेस न छोड़ें:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. अपने एपीआई अनुरोध के साथ फ़ील्ड मास्क भेजें. उदाहरण के लिए, cURL अनुरोध में, आपको -H और X-Goog-FieldMask के साथ फ़ील्ड मास्क की जानकारी देनी होगी:

   -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration

फ़ील्ड के रेफ़रंस

फ़ील्ड मास्क की मदद से, जवाब में जिन फ़ील्ड का अनुरोध किया जा सकता है उन्हें देखने के लिए, नीचे दी गई सूची में लिंक किए गए Routes API के रेफ़रंस देखें. रेफ़रंस में दिखाए गए तरीके से, फ़ील्ड को कैमल केस में डालें. उदाहरण के लिए, routePreference.

इन रेफ़रंस में, उपलब्ध फ़ील्ड शामिल होते हैं. हालांकि, फ़ील्ड मास्क का पूरा पाथ तय करने के लिए, आपको फ़ील्ड की हैरारकी देखनी होगी. फ़ील्ड की हैरारकी पाने के बारे में ज़्यादा जानने के लिए, यह तय करना कि आपको किस फ़ील्ड मास्क का इस्तेमाल करना है लेख पढ़ें.

• रास्ते के फ़ील्ड मास्क का हिसाब लगाना
  • REST: रिस्पॉन्स में, Route ऑब्जेक्ट के उन फ़ील्ड की जानकारी देता है जिन्हें दिखाना है. इन फ़ील्ड के नाम के आगे routes. लगा होता है. उदाहरण के लिए, routes.distanceMeters.
  • gRPC: रिटर्न किए जाने वाले रिस्पॉन्स में, Route ऑब्जेक्ट के फ़ील्ड के बारे में बताता है.
• Compute route matrix field masks
  • REST: यह बताता है कि रिस्पॉन्स में कौनसे फ़ील्ड दिखाने हैं.
  • gRPC: रिस्पॉन्स में, रिटर्न किए जाने वाले RouteMatrixElement ऑब्जेक्ट के फ़ील्ड तय करता है.

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

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

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

3. पिछले चरण में दिखाए गए फ़ील्ड की हैरारकी का इस्तेमाल करके, अपने फ़ील्ड मास्क बनाएं. इसके लिए, इस फ़ॉर्मैट का इस्तेमाल करें:

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

उदाहरण के लिए, किसी रास्ते से मिले इस अधूरे जवाब के लिए:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

अगर आपको रास्ते के हिस्से के लिए सिर्फ़ distanceMeters फ़ील्ड दिखाना है, तो इसका मतलब है कि आपको पिछले सैंपल में मौजूद आखिरी distanceMeters फ़ील्ड दिखाना है. इसके लिए, फ़ील्ड मास्क इस तरह का होना चाहिए:

routes.legs.distanceMeters

अगर आपको रास्ते के हर चरण के लिए distanceMeters फ़ील्ड दिखाना है, तो इसका मतलब है कि आपको पिछले सैंपल में steps में मौजूद distanceMeters दिखाना है. इसके लिए, फ़ील्ड मास्क इस तरह का होना चाहिए:

routes.legs.steps.distanceMeters

अगर आपको ऊपर दिए गए नतीजे के साथ, दोनों वैल्यू दिखानी हैं, तो आपका फ़ील्ड मास्क इस तरह का होगा:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

फ़ील्ड मास्क पाथ के उदाहरण

इस सेक्शन में, REST और gRPC कॉल में रिस्पॉन्स फ़ील्ड मास्क के हिस्से के तौर पर फ़ील्ड पाथ तय करने के तरीके के ज़्यादा उदाहरण दिए गए हैं.

computeRoutes पर REST कॉल

पहले उदाहरण में, किसी रास्ते का हिसाब लगाने के लिए, computeRoutes तरीके के साथ REST कॉल का इस्तेमाल किया गया है. इस उदाहरण में, हेडर में फ़ील्ड मास्क तय किए गए हैं, ताकि रिस्पॉन्स में रूट distanceMeters और duration फ़ील्ड दिखाए जा सकें. फ़ील्ड के नाम के आगे routes लगाना न भूलें.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

computeRouteMatrix पर REST कॉल

रूट मैट्रिक का हिसाब लगाने के लिए इस्तेमाल किए जाने वाले REST computeRouteMatrix तरीके के लिए, हेडर में बताएं कि ऑरिजिन और डेस्टिनेशन के हर कॉम्बिनेशन के लिए, originIndex, destinationIndex, और duration दिखाएं:

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC कॉल

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

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

फ़ील्ड पाथ से जुड़ी बातें

सिर्फ़ ज़रूरी फ़ील्ड दिखाने के लिए, जवाब में सिर्फ़ वे फ़ील्ड शामिल करें जिनकी आपको ज़रूरत है:

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

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