选择要返回的信息

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

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

使用字段掩码是一种很好的设计做法, 不必要的数据,从而避免不必要的处理时间和已出账单费用。

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

定义响应字段掩码

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

构造并指定字段路径,如下所示:

  1. 通过 Routes API 查找包含您所需信息的字段。如需了解详情,请参阅字段引用
  2. 确定所需字段的路径,并为这些字段构建字段掩码:如需了解详情,请参阅确定要使用的字段掩码
  3. 将您需要的所有字段的字段掩码组合起来,并用英文逗号分隔字段掩码。例如,如需请求路线路程的 distanceMeters 加上每个路线路段的时长,请同时输入这两者,并用英文逗号分隔,不要有空格:

    routes.legs.distanceMeters,routes.legs.steps.duration
  4. 随 API 请求一起发送字段掩码。例如,在 cURL 请求中,您可以使用 -HX-Goog-FieldMask 指定字段掩码:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
如需查看示例和了解详情,请参阅以下部分。

字段引用

如需查看您可以通过字段掩码在响应中请求的字段,请参阅下方列表中链接的 Routes API 参考文档。请按照参考中所示,以驼峰命名法指定字段。例如 routePreference

这些引用包含可用字段;不过,您需要参考字段的层次结构来确定完整的字段掩码路径。如需详细了解如何获取字段的层次结构,请参阅确定要使用的字段掩码

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

确定要使用的字段掩码

您可以按照以下步骤确定要使用的字段,并为它们构建字段掩码:

  1. 使用字段掩码 * 请求所有字段
  2. 在响应中查看字段的层次结构,找到您需要的字段。
  3. 使用上一步中显示的字段层次结构构建字段掩码,格式如下:

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

例如,对于路由中的此部分响应:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

如果您只想返回路线路程的 distanceMeters 字段;即上述示例中的最后一个 distanceMeters,则字段掩码如下所示:

routes.legs.distanceMeters

如果您想改为返回路线分段的每个步骤的 distanceMeters 字段(即上例中 steps 下的 distanceMeters),则字段掩码如下所示:

routes.legs.steps.distanceMeters

如果希望同时返回上述结果,则字段掩码如下所示:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

字段掩码路径示例

本部分包含有关如何在 REST 和 gRPC 调用中将字段路径指定为响应字段掩码的更多示例。

computeRoutes 的 REST 调用

在第一个示例中,您使用 REST 调用 computeRoutes 计算方法 路径。在此示例中,您可以在标头中指定字段掩码,以在响应中返回路由 distanceMetersduration 字段。请务必为字段名称添加 routes 前缀。

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

computeRouteMatrix 的 REST 调用

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 调用

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

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

字段路径注意事项

仅在响应中添加所需的字段,以便仅返回所需的字段:

  • 缩短处理时间,以便以更短的延迟时间返回结果。
  • 确保稳定的延迟时间性能。如果您选择所有字段,或者选择顶级的所有字段,那么在添加新字段并自动将其包含在响应中后,您可能会遇到性能下降问题。
  • 缩减响应大小,从而提高网络吞吐量。
  • 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和已出账单费用。

有关构建字段掩码的详情,请参阅 field_mask.proto.

请求路线令牌

如需请求 Routes API 针对生成的路由返回路由令牌,请按以下步骤操作:

  1. 设置返回路由令牌所需的以下参数:
    • travelMode 设置为 DRIVE
    • routingPreference 设置为 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL
  2. 请检查并确保您的所有路线航点均不是 via 航点。
  3. 指定 routes.routeToken 字段掩码以返回路线令牌:
    X-Goog-FieldMask: routes.routeToken

您可以在 Navigation SDK 中使用规划路线的路线令牌。如需了解详情,请参阅规划路线(Android)规划路线(iOS)

路由令牌示例

以下是单源单目的地路线的 cURL 请求正文示例,其中使用字段掩码请求路线令牌以及路线时长、距离和路线多段线:

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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

如需了解详情,请参阅 Compute Routes API 参考文档