Method: computeRouteMatrix

接受出发地和目的地的列表，并返回一个包含每个出发地和目的地组合的路线信息的流。

注意：此方法要求您在输入中指定响应字段掩码。您可以使用网址参数 $fields 或 fields，也可以使用 HTTP/gRPC 标头 X-Goog-FieldMask 来提供响应字段掩码（请参阅可用的网址参数和标头）。该值是以英文逗号分隔的字段路径列表。请参阅这篇详细的文档，了解如何构建字段路径。

例如，在此方法中：

  • 所有可用字段的字段掩码（用于手动检查）：X-Goog-FieldMask: *
  • 路线时长、距离、元素状态、条件和元素指数的字段掩码（生产设置示例）：X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

请务必在字段掩码中添加 status，否则所有消息都会显示为“正常”。Google 不建议使用通配符 (*) 响应字段掩码，因为：

  • 仅选择您需要的字段有助于我们的服务器节省计算周期，从而使我们能够以更低的延迟时间向您返回结果。
  • 仅选择生产作业中需要的字段可确保稳定的延迟时间性能。我们未来可能会添加更多响应字段，而这些新字段可能需要额外的计算时间。如果您选择所有字段，或者选择顶级的所有字段，则可能会遇到性能下降的问题，因为我们添加的任何新字段都会自动包含在响应中。
  • 仅选择所需的字段可减小响应大小，从而提高网络吞吐量。

HTTP 请求

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
字段
origins[]

object (RouteMatrixOrigin)

必需。来源数组，用于确定响应矩阵的行。以下大小限制适用于来源和目的地的基数：

  • 指定为 placeId 或 address 的出发地数量与目的地数量之和不得超过 50。
  • 在任何情况下，出发地数量与目的地数量的乘积都不得超过 625。
  • 如果将 routingPreference 设置为 TRAFFIC_AWARE_OPTIMAL，则出发地数量与目的地数量的乘积不得超过 100。
  • 如果将 travelMode 设置为 TRANSIT，则出发地数量与目的地数量的乘积不得超过 100。
destinations[]

object (RouteMatrixDestination)

必需。目的地数组，用于确定响应矩阵的列。
travelMode

enum (RouteTravelMode)

可选。指定交通方式。
routingPreference

enum (RoutingPreference)

可选。指定如何计算路线。服务器会尝试使用所选的路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长，则返回错误。只有当 travelMode 为 DRIVE 或 TWO_WHEELER 时，您才能指定此选项，否则请求会失败。
departureTime

string (Timestamp format)

可选。出发时间。如果您未设置此值，则此值将默认为您发出请求的时间。注意：只有在 RouteTravelMode 设置为 TRANSIT 时，您才能指定过去的 departureTime。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"
arrivalTime

string (Timestamp format)

可选。到达时间。注意：只有当 RouteTravelMode 设置为 TRANSIT 时才能设置此项。您可以指定 departureTime 或 arrivalTime，但不能同时指定这两者。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"
languageCode

string

可选。BCP-47 语言代码，例如“en-US”或“sr-Latn”。如需了解详情，请参阅 Unicode 语言区域标识符。如需查看支持的语言列表，请参阅语言支持。如果您未提供此值，系统会根据第一个来源的位置推断显示语言。
regionCode

string

可选。地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。如需了解详情，请参阅国家/地区代码顶级网域。
units

enum (Units)

可选。指定显示字段的度量单位。
extraComputations[]

enum (ExtraComputation)

可选。可用于完成请求的额外计算的列表。注意：这些额外的计算可能会在响应中返回额外的字段。这些额外的字段还必须在字段掩码中指定，才能在响应中返回。
trafficModel

enum (TrafficModel)

可选。指定计算交通中的时间时要使用的假设。此设置会影响 RouteMatrixElement 中时长字段内返回的值，该值包含根据历史平均数据预测的交通时间。TrafficModel 仅适用于将 RoutingPreference 设置为 TRAFFIC_AWARE_OPTIMAL 且将 RouteTravelMode 设置为 DRIVE 的请求。如果请求了流量，但未指定 TrafficModel，则默认为 BEST_GUESS。
transitPreferences

object (TransitPreferences)

可选。指定影响为 TRANSIT 路线返回的路线的偏好设置。注意：只有在将 RouteTravelMode 设置为 TRANSIT 时，您才能指定 transitPreferences。

响应正文

包含针对 v2.computeRouteMatrix API 中的出发地/目的地对计算的路线信息。此 proto 可以流式传输到客户端。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
字段
status

object (Status)

相应元素的错误状态代码。
condition

enum (RouteMatrixElementCondition)

指示是否找到了路线。与状态无关。
distanceMeters

integer

路线的行驶距离（以米为单位）。
duration

string (Duration format)

导航路线所需的时间。如果您将 routingPreference 设置为 TRAFFIC_UNAWARE，则此值与 staticDuration 相同。如果您将 routingPreference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，则系统会根据路况计算此值。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
staticDuration

string (Duration format)

在不考虑路况的情况下，沿路线行驶所需的时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
travelAdvisory

object (RouteTravelAdvisory)

有关路线的其他信息。例如：限制信息和收费信息
fallbackInfo

object (FallbackInfo)

在某些情况下，如果服务器无法根据指定偏好设置计算特定起点/终点对的路线，则可能会改用其他计算模式。使用回退模式时，此字段包含有关回退响应的详细信息。否则，系统将取消设置此字段。
localizedValues

object (LocalizedValues)

RouteMatrixElement 的属性的文本表示形式。
originIndex

integer

请求中来源的索引（从零开始）。
destinationIndex

integer

请求中目的地的从零开始的索引。

RouteMatrixOrigin

ComputeRouteMatrixRequest 的单个起点

JSON 表示法 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
字段
waypoint

object (Waypoint)

必需。出发地航点
routeModifiers

object (RouteModifiers)

可选。将此作为起点的每条路线的修饰符

RouteMatrixDestination

ComputeRouteMatrixRequest 的单个目的地

JSON 表示法 
{
  "waypoint": {
    object (Waypoint)
  }
}
字段
waypoint

object (Waypoint)

必需。目的地途经点

ExtraComputation

完成请求时要执行的额外计算。

枚举
EXTRA_COMPUTATION_UNSPECIFIED 未使用。 包含此值的请求将失败。
TOLLS 矩阵元素的通行费信息。

RouteMatrixElementCondition

返回的路线的状况。

枚举
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED 仅在元素的 status 不为 OK 时使用。
ROUTE_EXISTS 找到了路线，并为相应元素填写了相应信息。
ROUTE_NOT_FOUND 找不到任何路线。包含路线信息的字段（例如 distanceMeters 或 duration）不会在元素中填写。

LocalizedValues

某些属性的文本表示形式。

JSON 表示法 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
字段
distance

object (LocalizedText)

以文本形式表示的行驶距离。
duration

object (LocalizedText)

以文本形式表示的时长，考虑了路况。注意：如果未请求路况信息，则此值与 staticDuration 的值相同。
staticDuration

object (LocalizedText)

以文本形式表示的持续时间，未考虑路况。
transitFare

object (LocalizedText)

以文本形式表示的公交票价。