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

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

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

شما لیست فیلدهای مورد نیاز خود را در ماسک فیلد پاسخ مشخص می کنید. سپس با استفاده از پارامتر 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 مراجعه کنید.