Method: computeRouteMatrix

获取出发地和目的地列表,并返回包含每种出发地和目的地组合的路线信息的数据流。

注意:此方法要求您在输入中指定响应字段掩码。您可以通过以下两种方式提供响应字段掩码:使用网址参数 $fieldsfields,或者使用 HTTP/gRPC 标头 X-Goog-FieldMask(请参阅可用的网址参数和标头)。该值是以英文逗号分隔的字段路径列表。请参阅有关如何构造字段路径的详细文档。

例如,在此方法中:

  • 所有可用字段的字段掩码(用于手动检查):X-Goog-FieldMask: *
  • 路线时长、距离、元素状态、条件和元素索引的字段掩码(正式版设置示例):X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

请务必在字段掩码中加入 status,否则所有邮件都会正常显示。Google 不建议使用通配符 (*) 响应字段掩码,因为:

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

HTTP 请求

POST https://routespreferred.googleapis.com/v1:computeRouteMatrix

网址采用 gRPC 转码语法。

请求正文

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

JSON 表示法
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string
}
字段
origins[]

object (RouteMatrixOrigin)

必需。原点数组,用于确定响应矩阵的行。出发地和目的地的基数有以下几种大小限制:

  • 在任何情况下,元素(出发地 × 目的地)的数量都不得超过 625 个。
  • 如果路由 Preference 设置为 TRAFFIC_AWARE_OPTIMAL,那么元素(出发地 × 目的地)数量不得超过 100。
  • 指定为 placeId 的航点数(出发地 + 目的地)不得超过 50 个。
destinations[]

object (RouteMatrixDestination)

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

travelMode

enum (RouteTravelMode)

可选。指定交通方式。

routingPreference

enum (RoutingPreference)

可选。指定如何计算路线。服务器会尝试使用所选的路由偏好设置来计算路由。如果路由偏好设置导致错误或延迟时间过长,则返回错误。我们日后可能会实现后备机制,以便在首选选项无法给出有效结果时使用其他选项。只有在 travelModeDRIVETWO_WHEELER 时才能指定此选项,否则请求会失败。

departureTime

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

响应正文

如果成功,则响应正文包含一个 RouteMatrixElement 实例。

授权作用域

需要以下 OAuth 范围:

  • https://www.googleapis.com/auth/maps-platform.routespreferred

如需了解详情,请参阅 OAuth 2.0 概览