انتخاب کنید چه اطلاعاتی باید بازگردانده شود

هنگامی که متدی را برای محاسبه مسیر یا محاسبه ماتریس مسیر فراخوانی می کنید، باید مشخص کنید که چه اطلاعاتی را می خواهید با تعیین اینکه کدام فیلدها را می خواهید در پاسخ بازگردانید. هیچ لیست پیش فرضی از فیلدهای برگشتی وجود ندارد. اگر این لیست را حذف کنید، متدها با خطا مواجه می شوند.

شما با ایجاد یک ماسک فیلد پاسخ، لیست فیلد را مشخص می کنید. سپس با استفاده از پارامتر URL $fields یا fields ، یا با استفاده از هدر HTTP یا gRPC X-Goog-FieldMask ماسک فیلد پاسخ را به هر یک از روش‌ها ارسال می‌کنید.

پوشاندن میدان یک روش طراحی خوب برای اطمینان از عدم درخواست داده‌های غیرضروری است که به جلوگیری از زمان پردازش غیر ضروری و هزینه‌های صورت‌حساب کمک می‌کند.

برای اطلاعات بیشتر در مورد پارامترهای URL، به پارامترهای سیستم مراجعه کنید.

ماسک فیلد پاسخ را تعریف کنید

ماسک فیلد پاسخ، لیستی از مسیرها است که با کاما از هم جدا شده‌اند، که در آن هر مسیر یک فیلد منحصر به فرد را در پیام پاسخ مشخص می‌کند. مسیر از پیام پاسخ سطح بالا شروع می شود و از یک مسیر جدا شده با نقطه به فیلد مشخص شده استفاده می کند.

یک مسیر فیلد به صورت زیر بسازید:

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

• ماسک میدان مسیر را محاسبه کنید
  • REST: فیلدهای شی Route را در پاسخ به بازگشت، با پیشوند routes. برای مثال routes.distanceMeters .
  • gRPC: فیلدهای شی Route را در پاسخ به بازگشت مشخص می کند.
• ماسک های فیلد ماتریس مسیر را محاسبه کنید
  • REST: فیلدهای بدنه Response را برای بازگشت مشخص می کند.
  • gRPC: فیلدهای شی RouteMatrixElement را در پاسخ بازگشت مشخص می کند.

برای اطلاعات بیشتر در مورد نحوه ساخت فیلد ماسک، به field_mask.proto مراجعه کنید.

تعیین کنید که از چه ماسک هایی استفاده کنید

در اینجا نحوه تعیین فیلد ماسک هایی که می خواهید استفاده کنید آمده است:

1. همه فیلدها را با استفاده از یک فیلد ماسک * درخواست کنید.
2. به سلسله مراتب فیلدها در پاسخ نگاه کنید و تعیین کنید چه فیلدهایی را می خواهید.
3. ماسک فیلد خود را با استفاده از سلسله مراتب فیلد بسازید.

به عنوان مثال، برای این پاسخ جزئی از یک مسیر ترانزیت:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

اگر می خواهید فقط فیلد distanceMeters را برگردانید، ماسک فیلد شما این است:

routes.legs.distanceMeters

مثال دیگر: برای برگرداندن همه چیز زیر legs در پاسخ، ماسک فیلد شما این است:

routes.legs

یک مسیر میدانی را مشخص کنید

این بخش شامل مثال هایی در مورد نحوه تعیین یک مسیر فیلد به عنوان بخشی از یک ماسک فیلد پاسخ است.

REST تماس با computeRoutes

در مثال اول، شما از یک فراخوانی REST به روش computeRoutes برای محاسبه مسیر استفاده می کنید. در این مثال، در هدر، ماسک‌های فیلد را مشخص می‌کنید تا فیلدهای Route.distanceMeters و Route.duration را در پاسخ برگردانند. به یاد داشته باشید که نام فیلد را بر اساس routes پیشوند کنید.

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

تماس REST با computeRouteMatrix

برای روش REST computeRouteMatrix که برای محاسبه یک ماتریس مسیر استفاده می‌شود، در هدر، مشخص کنید که originIndex ، destinationIndex و duration برای هر ترکیب مبدا و مقصد برمی‌گردد:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

تماس gRPC

برای gRPC، یک متغیر حاوی ماسک فیلد پاسخ تنظیم کنید. سپس می توانید آن متغیر را به درخواست ارسال کنید.

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

ملاحظات مسیر میدانی

فقط فیلدهایی را که نیاز دارید در پاسخ وارد کنید. فقط فیلدهایی را که نیاز دارید برگردانید:

• زمان پردازش را کاهش می دهد ، بنابراین نتایج شما با تاخیر کمتری برمی گردند.
• اگر API فیلدهای پاسخ بیشتری را در آینده اضافه کند و آن فیلدهای جدید به زمان محاسبات اضافی نیاز داشته باشند ، عملکرد تأخیر پایدار را تضمین می کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است زمانی که همه فیلدهای جدید به طور خودکار در پاسخ شما گنجانده شوند، کاهش عملکرد را تجربه کنید.
• منجر به اندازه پاسخ کوچکتر می شود که به توان عملیاتی شبکه بالاتر تبدیل می شود.
• اطمینان حاصل می کند که داده های غیر ضروری را درخواست نمی کنید ، که به جلوگیری از زمان پردازش غیر ضروری و هزینه های صورتحساب کمک می کند.

درخواست یک نشانه مسیر

برای درخواست اینکه Routes API نشانه های مسیر را برای مسیرهای تولید شده برمی گرداند، الزامات برای برگرداندن یک نشانه مسیر را دنبال کنید و سپس از ماسک فیلد routes.route_token برای درخواست رمز استفاده کنید:

1. travel_mode را روی DRIVING تنظیم کنید.
2. routing_preference را روی TRAFFIC_AWARE یا TRAFFIC_AWARE_OPTIMAL تنظیم کنید.
3. بررسی کنید که هیچ یک از نقاط بین مسیر شما via ایستگاه های بین راه نباشد.
4. ماسک فیلد نشانه مسیر را مشخص کنید:

   -H X-Goog-FieldMask: routes.route_token

می توانید از مسیر برنامه ریزی شده خود در 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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

برای جزئیات بیشتر، به مرجع Compute Routes API مراجعه کنید.