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,
  "languageCode": string,
  "regionCode": string,
  "extraComputations": [
    enum (ExtraComputation)
  ]
}
字段
origins[]

object (RouteMatrixOrigin)

必需。一组源站，用于确定响应矩阵的行。对于源站和目的地的基数，有一些大小限制：

  • 在任何情况下，元素（起点 × 终点）的数量均不得超过 625。
  • 如果 routesPreference 设置为 TRAFFIC_AWARE_OPTIMAL，元素（源站 × 目的地）的数量不得超过 100 个。
  • 指定为 placeId 的路径点（起点 + 终点）数量不得超过 50 个。
destinations[]

object (RouteMatrixDestination)

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

enum (RouteTravelMode)

（可选）指定交通方式。
routingPreference

enum (RoutingPreference)

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

string (Timestamp format)

（可选）出发时间。如果未设置此值，则默认为发出请求的时间。如果您将此值设为已经发生的时间，请求将会失败。

时间戳采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式，分辨率为纳秒，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
languageCode

string

（可选）BCP-47 语言代码，例如“en-US”或“sr-Latn”。如需了解详情，请参阅 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。请参阅语言支持，获取支持的语言列表。如果未提供此值，显示语言将根据第一个来源的位置推断出来。
regionCode

string

（可选）地区代码，指定为 ccTLD（“顶级域名”）双字符值。有关详情，请参阅 https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains
extraComputations[]

enum (ExtraComputation)

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

响应正文

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

封装为 v2.computeRouteMatrix API 中的起点/终点对计算的路线信息。此 proto 可流式传输到客户端。

JSON 表示法 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "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)

在某些情况下，当服务器无法根据此特定起点/目的地对计算指定路线时，可能会回退到使用其他计算模式。使用回退模式时，此字段包含有关回退响应的详细信息。否则，该字段将处于未设置状态。
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)

必需。目的地航点

额外计算

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

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

RouteMatrixElementCondition

所返回路线的条件。

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