选择要返回的信息
当您调用一个方法来计算路线或路线矩阵时, 您必须列出要提供哪些信息 返回。没有返回字段的默认列表。如果省略此列表,这些方法会返回错误。
您可以通过创建响应字段掩码来指定字段列表。然后,您将传递
使用网址参数 $fields
或
fields
,或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask
。
使用字段掩码是一种很好的设计做法, 不必要的数据,从而避免不必要的处理时间和已出账单费用。
有关网址参数的详情,请参阅 系统参数。
定义响应字段掩码
响应字段掩码是以英文逗号分隔的路径列表,其中每个 path 用于指定响应消息中的唯一字段。 该路径从顶级响应消息开始,并使用 指定字段的路径(以英文句点分隔)。
构造并指定字段路径,如下所示:
- 通过 Routes API 查找包含您所需信息的字段。如需了解详情,请参阅字段引用。
- 确定所需字段的路径,并为这些字段构建字段掩码:如需了解详情,请参阅确定要使用的字段掩码。
合并您需要的所有字段的字段掩码,并用英文逗号分隔字段掩码。例如,如需请求路线路程的
distanceMeters
加上每个路线路段的时长,请同时输入这两者,并用英文逗号分隔,不要有空格:routes.legs.distanceMeters,routes.legs.steps.duration
随 API 请求一起发送字段掩码。例如,在 c网址 请求中,您可以使用
-H
和X-Goog-FieldMask
指定字段掩码:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
字段引用
要查看可通过字段掩码在响应中请求的字段,请参阅以下列表中链接的 Routes API 参考。请按照参考中所示,以驼峰命名法指定字段。例如 routePreference
。
这些参考资料包括可用的字段;不过,您需要参考字段的层次结构来确定完整的字段掩码路径。如需详细了解如何获取字段层次结构,请参阅确定要使用的字段掩码。
- 计算路由字段掩码 <ph type="x-smartling-placeholder">
- 计算路由矩阵字段掩码
<ph type="x-smartling-placeholder">
- </ph>
- REST:指定 响应正文 返回。
- gRPC:指定 RouteMatrixElement 对象。
确定要使用的字段掩码
下面介绍了如何确定要使用的字段,并为这些字段构建字段掩码:
- 使用字段掩码
*
请求所有字段。 - 查看响应中字段的层次结构, 字段。
使用上一步中显示的字段层次结构构建字段掩码,格式如下:
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
计算方法
路径。在此示例中,您可以在标头中指定字段掩码,以在响应中返回路由 distanceMeters
和 duration
字段。请务必为字段名称添加 routes
前缀。
X-Goog-FieldMask: routes.distanceMeters,routes.duration
对 computeRouteMatrix
的 REST 调用
对于 REST computeRouteMatrix
用于计算路线矩阵的方法,在标头中指定要返回的
originIndex
、destinationIndex
和 duration
(针对每种来源组合)
和目标:
X-Goog-FieldMask: originIndex,destinationIndex,duration
gRPC 调用
对于 gRPC,请设置包含响应字段掩码的变量。然后,您可以将该变量传递给请求。
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
字段路径注意事项
仅在响应中加入所需字段,以仅返回 所需的字段:
- 缩短处理时间,从而以更短的延迟时间返回结果。
- 确保稳定的延迟时间性能。如果您 也可以选择所有字段;如果您选择顶级的所有字段, 添加新字段,然后 自动包含在回复中
- 减小响应大小,从而提高网络吞吐量。
- 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和已出账单费用。
有关构建字段掩码的详情,请参阅 field_mask.proto.
请求路由令牌
如需请求 Routes API 针对生成的路由返回路由令牌,请按以下步骤操作:
- 设置返回路由令牌所需的以下参数:
- 将
travelMode
设置为DRIVE
。 - 将
routingPreference
设置为TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
。
- 将
- 请检查并确保您的所有路线航点均不是
via
航点。 - 指定
routes.routeToken
字段掩码以返回路由令牌:X-Goog-FieldMask: routes.routeToken
您可以在 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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
有关详情,请参阅 Compute Routes API 参考文档。