欧洲经济区 (EEA) 开发者

选择要返回的字段

当您请求路线或路线矩阵时，必须使用字段掩码来指定响应应返回哪些信息。没有返回字段的默认列表。如果您未指定字段掩码，这些方法会返回错误。

使用字段掩码还可以确保您不会请求不必要的数据，这有助于缩短响应延迟时间，并避免返回系统不需要的信息。

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

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

定义响应字段掩码

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

按如下方式构建和指定字段路径：

  1. 找到包含所需信息的字段 。如需了解详情，请参阅字段引用。
  2. 确定所需字段的路径，并为其构建字段掩码：如需了解详情，请参阅确定要使用的字段掩码。

  3. 合并所有所需字段的字段掩码，并用英文逗号分隔字段掩码。例如，如需请求路线路段的 distanceMeters，以及每个路线路段步骤的时长，请同时输入这两个字段，并用英文逗号分隔，且不留空格：

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

  4. 将字段掩码随 API 请求一起发送 。例如，在 curl 请求中，您可以使用 -H 和 X-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 方法来计算 路线。在此示例中，您在标头中指定字段掩码，以在响应中返回路线 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。