توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

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

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

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

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

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

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

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

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

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

فراخوانی gRPC

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

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

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

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

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

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