انتخاب فیلدها برای برگرداندن

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

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

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

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

تعریف پوشش فیلد پاسخ

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

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

1. فیلدهایی را که حاوی اطلاعات موردنیاز شما هستند پیدا کنید. برای جزئیات، به مرجع‌های فیلد مراجعه کنید.
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 Compute Routes یا Compute Route Matrix که در فهرست زیر پیوند داده شده‌اند مراجعه کنید. فیلدها را به‌صورت نگارش شتری همان‌طور که در مرجع نشان داده شده است مشخص کنید. برای مثال، routePreference.

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

• محاسبه پوشش فیلد مسیر
  • REST: فیلدهای شیء Route را در پاسخ برای برگرداندن مشخص می‌کند، با پیشوند routes.، برای مثال، routes.distanceMeters.
  • ‫gRPC: فیلدهای شیء مسیر را در پاسخ برای برگشتن مشخص می‌کند.
• پوشش‌های فیلد «محاسبه ماتریس مسیر»
  • REST: فیلدهای بدنه پاسخ را برای برگرداندن مشخص می‌کند.
  • 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 با computeRoutes

برای روش gRPC computeRoutes که برای محاسبه مسیر استفاده می‌شود، متغیری حاوی ماسک فیلد پاسخ تنظیم کنید تا فیلدهای مسیر distanceMeters، duration، و چندخطی کدگذاری‌شده را در پاسخ برگرداند. سپس می‌توانید آن متغیر را به درخواست ارسال کنید:

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

تماس gRPC با computeRouteMatrix

برای روش gRPC computeRouteMatrix که برای محاسبه ماتریس مسیر استفاده می‌شود، متغیری حاوی ماسک فیلد پاسخ تنظیم کنید تا برگرداندن originIndex، destinationIndex، و duration را برای هر ترکیب مبدأ و مقصد مشخص کند. سپس می‌توانید آن متغیر را به درخواست ارسال کنید:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

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

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

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

برای جزئیات بیشتر درباره ساختن ماسک فیلد، field_mask.proto را ببینید.