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

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

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

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

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

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 का रेफ़रंस देखें.