选择要返回的信息

调用方法来计算路线或计算路线矩阵时,您必须通过指定要在响应中返回的字段来指定所需的信息。没有默认的已返回字段列表。如果省略此列表,这些方法会返回错误。

您可以通过创建响应字段掩码来指定字段列表。然后,您可以使用网址参数 $fieldsfields,或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask 将响应字段掩码传递给任一方法。

字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和产生费用。

如需详细了解网址参数,请参阅系统参数

定义响应字段掩码

响应字段掩码是一个以英文逗号分隔的路径列表,其中每个路径指定响应消息中的唯一字段。该路径从顶级响应消息开始,并使用以英文句点分隔的路径到指定字段。

按如下方式构造字段路径:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • 计算路由字段掩码
    • REST:指定要返回的响应中 Route 对象的字段,以 routes. 为前缀,例如 routes.distanceMeters
    • gRPC:指定要返回的响应中 Route 对象的字段。
  • 计算路线矩阵字段掩码

如需详细了解如何构建字段掩码,请参阅 field_mask.proto

确定要使用的字段掩码

下面介绍了如何确定要使用的字段掩码:

  1. 使用字段掩码 * 请求所有字段。
  2. 查看响应中字段的层次结构,并确定您所需的字段。
  3. 使用字段层次结构构建字段掩码。

例如,对于来自公交路线的这一部分响应:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

如果您只想返回 distanceMeters 字段,则字段掩码为:

routes.legs.distanceMeters

另一个示例:如需返回响应中 legs 下的所有内容,字段掩码如下:

routes.legs

指定字段路径

本部分举例说明了如何将字段路径指定为响应字段掩码的一部分。

computeRoutes 的 REST 调用

在第一个示例中,您使用 REST 调用 computeRoutes 方法来计算路线。在此示例中,您需要在标头中指定字段掩码以返回响应中的 Route.distanceMetersRoute.duration 字段。请务必为字段名称添加 routes 前缀。

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

computeRouteMatrix 的 REST 调用

对于用于计算路线矩阵的 REST computeRouteMatrix 方法,请在标头中指明针对出发地和目的地的每个组合返回 originIndexdestinationIndexduration

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 调用

对于 gRPC,请设置包含响应字段掩码的变量。然后,您可以将该变量传递给请求。

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

字段路径注意事项

请在响应中仅添加您所需的字段。仅返回您需要的字段:

  • 减少处理时间,从而以更短的延迟时间返回结果。
  • 如果 API 将来会添加更多响应字段,并且这些新字段需要额外的计算时间,则可以确保稳定的延迟性能。如果您选择所有字段,或者选择顶级所有字段,那么当所有新字段都自动包含在响应中时,性能可能会降低。
  • 响应大小更小,这意味着网络吞吐量更高。
  • 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和计费费用。

请求路由令牌

如需请求 Routes API 返回生成的路由的路由令牌,请遵循返回路由令牌的要求,然后使用 routes.route_token 字段掩码请求令牌:

  1. travel_mode 设为 DRIVING
  2. routing_preference 设置为 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL
  3. 请检查您的所有航点都不是 via 航点。
  4. 指定路由令牌字段掩码:
    -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 参考文档