चुनें कि कौनसी जानकारी वापस लानी है

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

जवाब फ़ील्ड मास्क बनाकर, फ़ील्ड की सूची तय की जाती है. इसके बाद, यूआरएल पैरामीटर $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.

इसके उलट, आपको पैरामीटर की वैल्यू, यहां दिखाए गए तरीके से डालनी होंगी. उदाहरण के लिए, routingPreference के लिए, आपको TRAFFIC_AWARE डालना होगा.

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

• रास्ते के फ़ील्ड मास्क का हिसाब लगाना
  • 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"
)

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

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

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

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

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

रास्ते के टोकन का अनुरोध करना

Routes API से जनरेट किए गए रास्तों के लिए रास्ता टोकन दिखाने का अनुरोध करने के लिए, यह तरीका अपनाएं:

1. रूट टोकन दिखाने के लिए, ये पैरामीटर सेट करें:
   • travelMode को DRIVE पर सेट करें.
   • routingPreference को TRAFFIC_AWARE या TRAFFIC_AWARE_OPTIMAL पर सेट करें.
2. देखें कि आपके रास्ते के किसी भी वेपॉइंट में via वेपॉइंट शामिल न हों.
3. रूट टोकन दिखाने के लिए, routes.routeToken फ़ील्ड मास्क तय करें:

   X-Goog-FieldMask: routes.routeToken

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

नेविगेशन SDK टूल में, प्लान किए गए रास्ते के लिए रूट टोकन का इस्तेमाल किया जा सकता है. ज़्यादा जानकारी के लिए, रास्ता तय करना (Android) या रास्ता तय करना (iOS) लेख पढ़ें.

रूट टोकन का उदाहरण

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

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

ज़्यादा जानकारी के लिए, Compute Routes API का रेफ़रंस देखें.