选择要返回的信息
调用方法来计算路线或计算路线矩阵时,您必须通过指定要在响应中返回的字段来指定所需的信息。没有默认的已返回字段列表。如果省略此列表,这些方法会返回错误。
您可以通过创建响应字段掩码来指定字段列表。然后,您可以使用网址参数 $fields
或 fields
,或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask
将响应字段掩码传递给任一方法。
字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和产生费用。
如需详细了解网址参数,请参阅系统参数。
定义响应字段掩码
响应字段掩码是一个以英文逗号分隔的路径列表,其中每个路径指定响应消息中的唯一字段。该路径从顶级响应消息开始,并使用以英文句点分隔的路径到指定字段。
按如下方式构造字段路径:
topLevelField[.secondLevelField][.thirdLevelField][...]
- 计算路由字段掩码
- 计算路线矩阵字段掩码
- REST:指定要返回的响应正文的字段。
- gRPC:指定要返回的响应中 RouteMatrixElement 对象的字段。
如需详细了解如何构建字段掩码,请参阅 field_mask.proto。
确定要使用的字段掩码
下面介绍了如何确定要使用的字段掩码:
- 使用字段掩码
*
请求所有字段。 - 查看响应中字段的层次结构,并确定您所需的字段。
- 使用字段层次结构构建字段掩码。
例如,对于来自公交路线的这一部分响应:
"routes": [ { "legs": [ { "distanceMeters": 12886, } ... ]}]
如果您只想返回 distanceMeters
字段,则字段掩码为:
routes.legs.distanceMeters
另一个示例:如需返回响应中 legs
下的所有内容,字段掩码如下:
routes.legs
指定字段路径
本部分举例说明了如何将字段路径指定为响应字段掩码的一部分。
对 computeRoutes
的 REST 调用
在第一个示例中,您使用 REST 调用 computeRoutes
方法来计算路线。在此示例中,您需要在标头中指定字段掩码以返回响应中的 Route.distanceMeters
和 Route.duration
字段。请务必为字段名称添加 routes
前缀。
-H X-Goog-FieldMask: routes.distanceMeters,routes.duration
对 computeRouteMatrix
的 REST 调用
对于用于计算路线矩阵的 REST computeRouteMatrix
方法,请在标头中指明针对出发地和目的地的每个组合返回 originIndex
、destinationIndex
和 duration
:
-H X-Goog-FieldMask: originIndex,destinationIndex,duration
gRPC 调用
对于 gRPC,请设置包含响应字段掩码的变量。然后,您可以将该变量传递给请求。
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
字段路径注意事项
请在响应中仅添加您所需的字段。仅返回您需要的字段:
- 减少处理时间,从而以更短的延迟时间返回结果。
- 如果 API 将来会添加更多响应字段,并且这些新字段需要额外的计算时间,则可以确保稳定的延迟性能。如果您选择所有字段,或者选择顶级所有字段,那么当所有新字段都自动包含在响应中时,性能可能会降低。
- 响应大小更小,这意味着网络吞吐量更高。
- 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和计费费用。
请求路由令牌
如需请求 Routes API 返回生成的路由的路由令牌,请遵循返回路由令牌的要求,然后使用 routes.route_token
字段掩码请求令牌:
- 将
travel_mode
设为DRIVING
。 - 将
routing_preference
设置为TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
。 - 请检查您的所有航点都不是
via
航点。 - 指定路由令牌字段掩码:
-H X-Goog-FieldMask: routes.route_token
您可以在 Navigation SDK 中使用规划的路线。如需了解详情,请参阅规划路线 (Android) 或规划路线 (iOS)。
路由令牌示例
下面是一个出发地、单一目的地路线的 c网址 请求正文示例,其中使用字段掩码来请求路线令牌,以及路线时长、距离和路线多段线:
curl -X POST -d {"origin":{ "location": { "latLng":{ "latitude": -37.8167, "longitude": 144.9619 } } }, "destination":{ "location": { "latLng":{ "latitude":-37.8155, "longitude": 144.9663 } } }, "routingPreference":"TRAFFIC_AWARE", "travelMode":"DRIVE" } -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
如需了解详情,请参阅 Compute Routes API 参考文档。