هنگامی که متدی را برای محاسبه مسیر یا ماتریس مسیر فراخوانی می کنید، باید با فهرست کردن فیلدهایی که باید در پاسخ برگردانید، اطلاعاتی را که می خواهید مشخص کنید. هیچ لیست پیش فرضی از فیلدهای برگشتی وجود ندارد. اگر این لیست را حذف کنید، متدها با خطا مواجه می شوند.
شما با ایجاد یک ماسک فیلد پاسخ، لیست فیلد را مشخص می کنید. سپس با استفاده از پارامتر URL $fields یا fields ، یا با استفاده از هدر HTTP یا gRPC X-Goog-FieldMask ماسک فیلد پاسخ را به هر یک از روش‌ها ارسال می‌کنید.
استفاده از یک فیلد ماسک یک روش طراحی خوب است تا اطمینان حاصل شود که داده‌های غیرضروری درخواست نمی‌کنید، که به نوبه خود به جلوگیری از زمان پردازش غیر ضروری و هزینه‌های صورتحساب کمک می‌کند.
برای اطلاعات بیشتر در مورد پارامترهای URL، به پارامترهای سیستم مراجعه کنید.
ماسک فیلد پاسخ، لیستی از مسیرها است که با کاما از هم جدا شده‌اند، که در آن هر مسیر یک فیلد منحصر به فرد را در پیام پاسخ مشخص می‌کند. مسیر از پیام پاسخ سطح بالا شروع می شود و از یک مسیر جدا شده با نقطه به فیلد مشخص شده استفاده می کند.
یک مسیر فیلد را به صورت زیر بسازید و مشخص کنید:
- فیلدهایی را پیدا کنید که حاوی اطلاعات مورد نیاز شما از Routes API هستند. برای جزئیات، به مراجع فیلد مراجعه کنید.
- مسیرهای فیلدهای مورد نیاز خود را تعیین کنید و ماسک‌های فیلد را برای آنها بسازید : برای جزئیات، به تعیین اینکه از چه فیلد ماسکی می‌خواهید استفاده کنید، مراجعه کنید.
ماسک‌های فیلد را برای همه فیلدهایی که نیاز دارید ترکیب کنید ، ماسک‌های فیلد را با کاما از هم جدا کنید. به عنوان مثال، برای درخواست
distanceMetersبرای قسمت مسیر، به اضافه مدت زمان هر مرحله از مسیر، هر دو را با کاما از هم جدا کرده و بدون فاصله وارد کنید:routes.legs.distanceMeters,routes.legs.steps.duration
ماسک فیلد را با درخواست API خود ارسال کنید . به عنوان مثال، در یک درخواست cURL، ماسک فیلد را با
-HوX-Goog-FieldMaskمشخص می کنید:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
برای مشاهده فیلدهایی که می‌توانید در پاسخ از طریق فیلد ماسک‌ها درخواست کنید، به مراجع Routes API پیوند داده شده در لیست زیر مراجعه کنید. همانطور که در مرجع نشان داده شده است، فیلدها را در مورد شتر مشخص کنید. به عنوان مثال، routePreference .
این مراجع شامل فیلدهایی است که در دسترس هستند. با این حال، برای تعیین مسیر پوشش کامل فیلد، باید به سلسله مراتب فیلدها مراجعه کنید. برای جزئیات در مورد بدست آوردن سلسله مراتب فیلدها، به تعیین اینکه از چه فیلد ماسکی می خواهید استفاده کنید مراجعه کنید.
- ماسک میدان مسیر را محاسبه کنید
- ماسک های فیلد ماتریس مسیر را محاسبه کنید
- REST: فیلدهای بدنه Response را برای بازگشت مشخص می کند.
- gRPC: فیلدهای شی RouteMatrixElement را در پاسخ بازگشت مشخص می کند.
در اینجا نحوه تعیین اینکه از کدام فیلدها می خواهید استفاده کنید و ماسک فیلد برای آنها بسازید، آمده است:
- همه فیلدها را با استفاده از یک فیلد ماسک
*درخواست کنید. - به سلسله مراتب فیلدها در پاسخ برای فیلدهای مورد نظر خود نگاه کنید .
ماسک های فیلد خود را با استفاده از سلسله مراتب فیلدهای نشان داده شده در مرحله قبل و با استفاده از این فرمت بسازید :
topLevelField[.secondLevelField][.thirdLevelField][...]
به عنوان مثال، برای این پاسخ جزئی از یک مسیر:
"routes": [
{
"legs": [
{ "steps": [
{"distanceMeters": 119},
{"distanceMeters": 41} ]
}
],
"distanceMeters": 160
}
]
اگر می خواهید فقط قسمت distanceMeters را برای قسمت مسیر برگردانید. یعنی آخرین distanceMeters در نمونه قبلی، ماسک فیلد شما به صورت زیر است:
routes.legs.distanceMeters
اگر می خواهید به جای آن می خواهید قسمت distanceMeters را برای هر مرحله از مسیر مسیر برگردانید. یعنی distanceMeters زیر steps در نمونه قبلی، ماسک فیلد شما به شرح زیر است:
routes.legs.steps.distanceMeters
اگر می خواهید هر دو را برگردانید، با نتیجه بالا، فیلد ماسک شما به صورت زیر است:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
این بخش شامل مثال های بیشتری در مورد نحوه تعیین یک مسیر فیلد به عنوان بخشی از ماسک فیلد پاسخ در فراخوانی های REST و gRPC است.
computeRoutes در مثال اول، شما از یک فراخوانی REST به روش computeRoutes برای محاسبه مسیر استفاده می کنید. در این مثال، در هدر، ماسک‌های فیلد را مشخص می‌کنید تا فیلدهای distanceMeters و duration در پاسخ برگردانند. به یاد داشته باشید که نام فیلد را بر اساس routes پیشوند کنید.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
computeRouteMatrix برای روش REST computeRouteMatrix که برای محاسبه یک ماتریس مسیر استفاده می‌شود، در هدر، مشخص کنید که originIndex ، destinationIndex و duration برای هر ترکیب مبدا و مقصد برمی‌گردد:
X-Goog-FieldMask: originIndex,destinationIndex,duration
برای gRPC، یک متغیر حاوی ماسک فیلد پاسخ تنظیم کنید. سپس می توانید آن متغیر را به درخواست ارسال کنید.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
فقط فیلدهایی را که برای برگرداندن فقط فیلدهایی که نیاز دارید در پاسخ بگنجانید:
- زمان پردازش را کاهش می دهد ، بنابراین نتایج شما با تاخیر کمتری برمی گردند.
- عملکرد تأخیر پایدار را تضمین می کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است با افزودن فیلدهای جدید و سپس به طور خودکار در پاسخ شما، کاهش عملکرد را تجربه کنید.
- منجر به اندازه پاسخ کوچکتر می شود که به توان عملیاتی شبکه بالاتر تبدیل می شود.
- اطمینان حاصل می کند که داده های غیر ضروری را درخواست نمی کنید ، که به جلوگیری از زمان پردازش غیر ضروری و هزینه های صورتحساب کمک می کند.
برای جزئیات بیشتر در مورد ساخت یک فیلد ماسک، به field_mask.proto مراجعه کنید.
برای درخواست اینکه Routes API نشانه های مسیر را برای مسیرهای تولید شده برمی گرداند، این مراحل را دنبال کنید:
- پارامترهای زیر را برای برگرداندن یک نشانه مسیر مورد نیاز تنظیم کنید:
-
travelModeرا رویDRIVEتنظیم کنید. -
routingPreferenceرا رویTRAFFIC_AWAREیاTRAFFIC_AWARE_OPTIMALتنظیم کنید.
-
- بررسی کنید که هیچ یک از نقاط بین مسیر شما
viaایستگاه های بین راه نباشد. - ماسک فیلد
routes.routeTokenرا برای برگرداندن یک نشانه مسیر مشخص کنید:X-Goog-FieldMask: routes.routeToken
می توانید از نشانه مسیر برای مسیر برنامه ریزی شده خود در Navigation 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 مراجعه کنید.