选择要返回的信息

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

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

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

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

定义响应字段掩码

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

按如下所示构造字段路径：

topLevelField[.secondLevelField][.thirdLevelField][...]

注意：请勿在字段路径列表中的任何位置使用空格。

• 计算路由字段掩码
  • REST：指定要返回的响应中 Route 对象的字段，以 routes. 为前缀，例如 routes.distanceMeters。
  • gRPC：指定要返回的响应中 Route 对象的字段。
• 计算路由矩阵字段掩码
  • REST：指定要返回的响应正文的字段。
  • gRPC：指定要返回的响应中 RouteMatrixElement 对象的字段。

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

确定要使用的字段掩码

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

1. 使用字段掩码 * 请求所有字段。
   注意：尽管此通配符字段掩码可以在开发中使用，但请勿在生产环境中使用通配符 (*) 响应字段掩码。由于通过此字段掩码请求更高级的功能，因此费用可能会高于预期，并且会增加响应延迟时间。请确保仅请求所需的字段，以最大限度地减少费用和请求响应时间。
2. 查看响应中字段的层次结构并确定所需的字段。
3. 使用字段层次结构构建字段掩码。

例如，对于某个公交路线的部分响应：

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

如果您只想返回 distanceMeters 字段，则字段掩码为：

routes.legs.distanceMeters

另一个示例：如需返回响应中 legs 下的所有内容，您的字段掩码为：

routes.legs

指定字段路径

本部分包含有关如何将字段路径指定为响应字段掩码一部分的示例。

注意：特殊情况字段掩码是通配符“*”，用于选择所有字段。但是，虽然此通配符字段掩码可以在开发中使用，但请勿在生产环境中使用。费用可能高于预期，因为高级功能是通过此字段掩码请求的，这会增加响应延迟时间。请确保仅请求所需的字段，以最大限度地减少费用和请求响应时间。

对 computeRoutes 的 REST 调用

在第一个示例中，您使用对 computeRoutes 方法的 REST 调用来计算路线。在此示例中，您可以在标头中指定字段掩码，以在响应中返回 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 在将来添加更多响应字段，并且这些新字段需要额外的计算时间，则可以确保稳定的延迟时间性能。如果您选择所有字段，或选择顶层的所有字段，则所有新字段都自动包含在响应中时，您可能会遇到性能下降的情况。
• 减小响应大小，从而提高网络吞吐量。
• 确保您不会请求不必要的数据，这有助于避免不必要的处理时间和已结算费用。

注意：解析响应消息且响应消息中的某个字段包含默认值时，即使您在响应字段掩码中指定了该字段，响应中也可能省略该字段。如需了解详情，请参阅语言指南 (proto3)。例如，计算路由矩阵时，响应的 distanceMeters 字段可以包含 0（默认值）。由于 0 是 distanceMeters 的默认值，因此响应中会省略该值。

请求路由令牌

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

1. 将 travel_mode 设置为 DRIVING。
2. 将 routing_preference 设置为 TRAFFIC_AWARE 或 TRAFFIC_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 参考文档。