با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
توسعه دهندگان منطقه اقتصادی اروپا (EEA).
فیلدهایی را برای بازگشت انتخاب کنید
وقتی ماتریس مسیر یا مسیر را درخواست می کنید، باید از یک فیلد ماسک استفاده کنید تا مشخص کنید پاسخ چه اطلاعاتی را باید بازگرداند. هیچ لیست پیش فرضی از فیلدهای برگشتی وجود ندارد. اگر یک فیلد ماسک را مشخص نکنید، متدها یک خطا برمی‌گردانند.
استفاده از یک فیلد ماسک همچنین تضمین می‌کند که داده‌های غیرضروری درخواست نمی‌کنید، که به نوبه خود به تأخیر پاسخ کمک می‌کند و از بازگرداندن اطلاعاتی که سیستم شما به آن نیاز ندارد جلوگیری می‌کند.
شما لیست فیلدهای مورد نیاز خود را در ماسک فیلد پاسخ مشخص می کنید. سپس با استفاده از پارامتر URL $fields یا fields ، یا با استفاده از هدر HTTP یا gRPC X-Goog-FieldMask ماسک فیلد پاسخ را به هر یک از روش‌ها ارسال می‌کنید.
برای اطلاعات بیشتر در مورد پارامترهای URL، به پارامترهای سیستم مراجعه کنید.
ماسک فیلد پاسخ را تعریف کنید
ماسک فیلد پاسخ، لیستی از مسیرها است که با کاما از هم جدا شده‌اند، که در آن هر مسیر یک فیلد منحصر به فرد را در پیام پاسخ مشخص می‌کند. مسیر از پیام پاسخ سطح بالا شروع می شود و از یک مسیر جدا شده با نقطه به فیلد مشخص شده استفاده می کند.
یک مسیر فیلد را به صورت زیر بسازید و مشخص کنید:
فیلدهایی را پیدا کنید که حاوی اطلاعات مورد نیاز شما هستند . برای جزئیات، به مراجع فیلد مراجعه کنید.
ماسک‌های فیلد را برای همه فیلدهایی که نیاز دارید ترکیب کنید ، ماسک‌های فیلد را با کاما از هم جدا کنید. به عنوان مثال، برای درخواست distanceMeters برای قسمت مسیر، به اضافه مدت زمان هر مرحله از مسیر، هر دو را با کاما از هم جدا کرده و بدون فاصله وارد کنید:
برای مثال و جزئیات بیشتر به بخش های زیر مراجعه کنید.
مراجع فیلد
برای مشاهده فیلدهایی که می‌توانید در پاسخ از طریق ماسک‌های فیلد درخواست کنید، به مراجع Routes API Compute Routes یا Compute Route Matrix در لیست زیر مراجعه کنید. همانطور که در مرجع نشان داده شده است، فیلدها را در مورد شتر مشخص کنید. به عنوان مثال، routePreference .
این مراجع شامل فیلدهایی است که در دسترس هستند. با این حال، برای تعیین مسیر پوشش کامل فیلد، باید به سلسله مراتب فیلدها مراجعه کنید. برای جزئیات بیشتر در مورد بدست آوردن سلسله مراتب فیلدها، به تعیین اینکه از چه فیلد ماسکی می خواهید استفاده کنید مراجعه کنید.
ماسک میدان مسیر را محاسبه کنید
REST: فیلدهای شی Route را در پاسخ به بازگشت، با پیشوند routes. برای مثال routes.distanceMeters .
gRPC: فیلدهای شی Route را در پاسخ به بازگشت مشخص می کند.
ماسک های فیلد ماتریس مسیر را محاسبه کنید
REST: فیلدهای بدنه Response را برای بازگشت مشخص می کند.
اگر می خواهید فقط قسمت distanceMeters را برای قسمت مسیر برگردانید. یعنی آخرین distanceMeters در نمونه قبلی، ماسک فیلد شما به صورت زیر است:
routes.legs.distanceMeters
اگر می خواهید به جای آن می خواهید قسمت distanceMeters را برای هر مرحله از مسیر مسیر برگردانید. یعنی distanceMeters زیر steps در نمونه قبلی، ماسک فیلد شما به شرح زیر است:
routes.legs.steps.distanceMeters
اگر می خواهید هر دو را برگردانید، با نتیجه بالا، فیلد ماسک شما به صورت زیر است:
این بخش شامل مثال های بیشتری در مورد نحوه تعیین یک مسیر فیلد به عنوان بخشی از ماسک فیلد پاسخ در فراخوانی های REST و gRPC است.
REST تماس با computeRoutes
در مثال اول، شما از یک فراخوانی REST به روش computeRoutes برای محاسبه مسیر استفاده می کنید. در این مثال، در هدر، ماسک‌های فیلد را مشخص می‌کنید تا فیلدهای distanceMeters و duration را در پاسخ برگردانند. به یاد داشته باشید که نام فیلد را بر اساس routes پیشوند کنید.
برای روش REST computeRouteMatrix که برای محاسبه یک ماتریس مسیر استفاده می‌شود، در هدر، مشخص کنید که originIndex ، destinationIndex و duration برای هر ترکیب مبدا و مقصد برمی‌گردد:
فقط فیلدهایی را که برای برگرداندن فقط فیلدهایی که نیاز دارید در پاسخ بگنجانید:
زمان پردازش را کاهش می دهد ، بنابراین نتایج شما با تاخیر کمتری برمی گردند.
عملکرد تأخیر پایدار را تضمین می کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است با افزودن فیلدهای جدید و سپس به طور خودکار در پاسخ شما، کاهش عملکرد را تجربه کنید.
منجر به اندازه پاسخ کوچکتر می شود که به توان عملیاتی شبکه بالاتر تبدیل می شود.
اطمینان حاصل می کند که داده های غیر ضروری را درخواست نمی کنید ، که به جلوگیری از زمان پردازش غیر ضروری و هزینه های صورتحساب کمک می کند.
برای جزئیات بیشتر در مورد ساخت یک فیلد ماسک، به field_mask.proto مراجعه کنید.
تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eWhen calling methods to compute routes or route matrices, you must specify the desired information using a response field mask to avoid errors and unnecessary charges.\u003c/p\u003e\n"],["\u003cp\u003eResponse field masks are comma-separated lists of field paths, starting from the top-level response message and using dot-separated paths to specific fields.\u003c/p\u003e\n"],["\u003cp\u003eUsing field masks is a best practice as it reduces processing time, response size, and costs by ensuring only necessary data is requested.\u003c/p\u003e\n"],["\u003cp\u003eYou can determine the required field masks by requesting all fields during development (using \u003ccode\u003e*\u003c/code\u003e), examining the response hierarchy, and constructing paths based on the field hierarchy.\u003c/p\u003e\n"],["\u003cp\u003eTo obtain route tokens for use in the Navigation SDK, set specific parameters, ensure no \u003ccode\u003evia\u003c/code\u003e waypoints, and include \u003ccode\u003eroutes.routeToken\u003c/code\u003e in the field mask.\u003c/p\u003e\n"]]],["When requesting route information, you must specify a **response field mask** to define which data fields to return. This is done via the `$fields`/`fields` URL parameter or the `X-Goog-FieldMask` header. The field mask is a comma-separated list of paths (e.g., `routes.legs.distanceMeters,routes.legs.steps.duration`), starting from the top-level response and using dot-notation to access nested fields. Use the API references to find available fields. Avoid requesting all fields with `*`, because that lead to higher cost and latency.\n"],null,["**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq).\n\n\u003cbr /\u003e\n\nChoose fields to return\n=======================\n\nWhen you request a route or route matrix, you must use a field mask to specify what information\nthe response should return. There is no default list of returned fields. If you don't specify a field mask, the methods return an error.\n\nUsing a field mask also ensures that you don't request\nunnecessary data, which in turn helps with response latency and avoids returning information your system doesn't need.\n\nYou specify the list of the fields you need in a **response field mask** . You then pass\nthe response field mask to either method by using the URL parameter `$fields` or\n`fields`, or by using the HTTP or gRPC header `X-Goog-FieldMask`.\n\nFor more information about URL parameters, see\n[System Parameters](https://cloud.google.com/apis/docs/system-parameters).\n\nDefine a response field mask\n----------------------------\n\nThe response field mask is a comma-separated list of paths, where each\npath specifies a unique field in the response message.\nThe path starts from the top-level response message and uses a\ndot-separated path to the specified field.\n\nConstruct and specify a field path as follows:\n\n1. **Find the fields that contain the information you need** . For details, see [Field References](#field-ref).\n2. **Determine the paths for the fields you need and construct the field masks for them** : For details, see [Determine what field mask you want to use](#determine-field-mask).\n3. **Combine the field masks for all of the fields you need** , separating the field masks with commas. For example, to request the `distanceMeters` for the route leg, plus the duration for each route leg step, enter them both, separated by a comma, with no spaces:\n\n ```\n routes.legs.distanceMeters,routes.legs.steps.duration\n ```\n4. **Send the field mask with your API request** . For example, in a curl request, you would specify the field mask with `-H` and `X-Goog-FieldMask`:\n\n ```\n -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration\n ```\n\nFor examples and more details, see the following sections.\n\n### Field References\n\nTo see the fields that you can request in a response through field masks, refer to the Routes API Compute Routes or Compute Route Matrix references linked in the following list. Specify fields in camel case as shown in the reference. For example, `routePreference`.\n| In contrast, you must enter parameter **values** as shown. For example, for `routingPreference`, you must enter `TRAFFIC_AWARE`.\n\nThese references include the fields that are available; however, you need to refer to the hierarchy of the fields to determine the full field mask path. For details on getting the hierarchy of the fields, see [Determine what field mask you want to use](#determine-field-mask).\n\n- **Compute route field mask**\n - REST: Specifies the fields of the [Route](/maps/documentation/routes/reference/rest/v2/TopLevel/computeRoutes#Route) object in the response to return, prefixed by `routes.`, for example, `routes.distanceMeters`.\n - gRPC: Specifies the fields of the [Route](/maps/documentation/routes/reference/rpc/google.maps.routing.v2#route) object in the response to return.\n- **Compute Route Matrix field masks**\n - REST: Specifies the fields of the [Response body](/maps/documentation/routes/reference/rest/v2/TopLevel/computeRouteMatrix#response-body) to return.\n - gRPC: Specifies the fields of the [RouteMatrixElement](/maps/documentation/routes/reference/rpc/google.maps.routing.v2#routematrixelement) object in the response to return.\n\n### Determine what field masks to use\n\nHere's how you can determine which fields you want to use, and construct the field masks for them:\n\n1. **Request all fields** using a field mask of `*`. **Caution:** While you can use this wildcard field mask while in development to determine what fields you need, don't use it in production. Requesting all fields in production results in higher costs and longer response times. Your cost may also increase unexpectedly as more advanced features are added, since this field mask will automatically include them. Instead, request only the fields you need to minimize your costs and request response time.\n2. **Look at the hierarchy of the fields** in the response for the fields you want.\n3. **Construct your field masks** using the hierarchy of the fields shown in the previous step, using this format:\n\n ```\n topLevelField[.secondLevelField][.thirdLevelField][...]\n ```\n | **Note:** Don't use spaces anywhere in the list of field paths.\n\nFor example, for this partial response from a route: \n\n```json\n\"routes\": [\n {\n \"legs\": [\n { \"steps\": [\n {\"distanceMeters\": 119},\n {\"distanceMeters\": 41} ]\n }\n ],\n \"distanceMeters\": 160\n }\n]\n```\n\nIf you want to return only the `distanceMeters` field for the route leg; that is, the last `distanceMeters` in the preceding sample, your field mask is as follows: \n\n```\nroutes.legs.distanceMeters\n```\n\nIf you want instead want to return the `distanceMeters` field for each step of the route leg; that is, the `distanceMeters` under `steps` in the preceding sample, your field mask is as follows: \n\n```\nroutes.legs.steps.distanceMeters\n```\n\nIf you want to return both, with the result above, your field mask is as follows: \n\n```\nroutes.legs.distanceMeters,routes.legs.steps.distanceMeters\n```\n\nExample field mask paths\n------------------------\n\nThis section contains more examples on how to specify a field path as part of a response field mask in REST and gRPC calls.\n\n### REST call to `computeRoutes`\n\nIn the first example, you use a REST call to the\n[`computeRoutes`](/maps/documentation/routes/reference/rest/v2/TopLevel/computeRoutes) method to calculate\na route. In this example, in the header, you specify field masks to return the route `distanceMeters` and `duration` fields in the response. Remember to prefix the field name by `routes`. \n\n```restructuredtext\nX-Goog-FieldMask: routes.distanceMeters,routes.duration\n```\n\n### REST call to `computeRouteMatrix`\n\nFor the REST [`computeRouteMatrix`](/maps/documentation/routes/reference/rest/v2/TopLevel/computeRouteMatrix)\nmethod used to compute a route matrix, in the header, specify to return\n`originIndex`, `destinationIndex`, and `duration` for each combination of origin\nand destination: \n\n```restructuredtext\nX-Goog-FieldMask: originIndex,destinationIndex,duration\n```\n\n### gRPC call\n\nFor gRPC, set a variable containing the response field mask. You can then pass that variable to the request. \n\n```gdscript\nconst (\n fieldMask = \"routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline\"\n)\n```\n\nField path considerations\n-------------------------\n\nInclude only the fields that you require in the response to return just the\nfields that you need:\n\n- **Decreases processing times**, so your results are returned with a lower latency.\n- **Ensures stable latency performance**. If you select all fields, or if you select all fields at the top level, you might experience performance degradation when new fields are added and then are automatically included in your response.\n- **Results in a smaller response size**, which translates into higher network throughput.\n- **Ensures that you don't request unnecessary data**, which helps to avoid unnecessary processing time and billed charges.\n\n| **Note:** When a response message is parsed, and a field in the response message contains its default value, the field may be omitted from the response even if you specified it in the response field mask. For more information, see the [Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3#default). For example, when you compute a route matrix, the `distanceMeters` field of the response can contain a value of 0, its default value. Because 0 is the default value of `distanceMeters`, it is omitted from the response.\n\nFor more details on constructing a field mask, see the\n[field_mask.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto)."]]
