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

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

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

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

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

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

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

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

  1. فیلدهایی را پیدا کنید که حاوی اطلاعات مورد نیاز شما از Routes API هستند. برای جزئیات، به مراجع فیلد مراجعه کنید.
  2. مسیرهای فیلدهای مورد نیاز خود را تعیین کنید و ماسک‌های فیلد را برای آنها بسازید : برای جزئیات، به تعیین اینکه از چه فیلد ماسکی می‌خواهید استفاده کنید، مراجعه کنید.

  3. ماسک‌های فیلد را برای همه فیلدهایی که نیاز دارید ترکیب کنید ، ماسک‌های فیلد را با کاما از هم جدا کنید. به عنوان مثال، برای درخواست distanceMeters برای قسمت مسیر، به اضافه مدت زمان هر مرحله از مسیر، هر دو را با کاما از هم جدا کرده و بدون فاصله وارد کنید:

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

  4. ماسک فیلد را با درخواست API خود ارسال کنید . به عنوان مثال، در یک درخواست 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 را در پاسخ به بازگشت مشخص می کند.
  • ماسک های فیلد ماتریس مسیر را محاسبه کنید
    • REST: فیلدهای بدنه Response را برای بازگشت مشخص می کند.
    • gRPC: فیلدهای شی RouteMatrixElement را در پاسخ بازگشت مشخص می کند.

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

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

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

  3. ماسک های فیلد خود را با استفاده از سلسله مراتب فیلدهای نشان داده شده در مرحله قبل و با استفاده از این فرمت بسازید :

    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 است.

REST تماس با computeRoutes

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

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

تماس REST با computeRouteMatrix

برای روش 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 مراجعه کنید.

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

برای درخواست اینکه Routes API نشانه های مسیر را برای مسیرهای تولید شده برمی گرداند، این مراحل را دنبال کنید:

  1. پارامترهای زیر را برای برگرداندن یک نشانه مسیر مورد نیاز تنظیم کنید:
    • travelMode روی DRIVE تنظیم کنید.
    • routingPreference روی TRAFFIC_AWARE یا TRAFFIC_AWARE_OPTIMAL تنظیم کنید.
  2. بررسی کنید که هیچ یک از نقاط بین مسیر شما via ایستگاه های بین راه نباشد.
  3. ماسک فیلد 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 مراجعه کنید.