فیلدهای موردنظر را برای برگرداندن انتخاب کنید

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

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

فهرست فیلدهای موردنیازتان را در ماسک فیلد پاسخ مشخص می‌کنید. سپس بااستفاده از پارامتر نشانی وب $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: فیلدهای شیء Route را در پاسخ برای برگرداندن مشخص می‌کند.
• ماسک‌های فیلد Compute Route Matrix
  • 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 را ببینید.