Method: projects.locations.optimizeTours

发送包含 ShipmentModel 的 OptimizeToursRequest，并返回包含 ShipmentRoute 的 OptimizeToursResponse，ShipmentRoute 是一组由车辆执行的路线，可最大限度地降低总体成本。

ShipmentModel 模型主要由需要执行的 Shipment 和可用于传送 Shipment 的 Vehicle 组成。ShipmentRoute 会将 Shipment 分配给 Vehicle。更具体地说，他们会为每辆车分配一系列 Visit，其中每个 Visit 都对应一个 VisitRequest，即 Shipment 的取货或送货。

目标是提供一种将 ShipmentRoute 分配给 Vehicle 的方案，以最大限度地降低总费用，其中费用在 ShipmentModel 中定义了多个组成部分。

HTTP 请求

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*/locations/*}:optimizeTours

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。定位项目或位置以进行呼叫。

格式：

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

如果未指定位置，系统将自动选择区域。

请求正文

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

JSON 表示法 
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
字段
timeout

string (Duration format)

如果设置了此超时时间，服务器会在超时时间段结束之前或同步请求的服务器截止时间到达之前（以较早者为准）返回响应。

对于异步请求，服务器会在超时时间结束之前生成解决方案（如果可能）。

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

object (ShipmentModel)

要解决的运输模型。
solvingMode

enum (SolvingMode)

默认情况下，求解模式为 DEFAULT_SOLVE (0)。
searchMode

enum (SearchMode)

用于解决请求的搜索模式。
injectedFirstSolutionRoutes[]

object (ShipmentRoute)

引导优化算法找到与之前解决方案类似的首个解决方案。

在构建第一个解决方案时，模型会受到限制。在第一个解决方案中，未在路线中执行的任何配送都会被隐式跳过，但在后续解决方案中可能会执行这些配送。

解决方案必须满足一些基本有效性假设：

  • 对于所有路线，vehicleIndex 必须在范围内且不得重复。
  • 对于所有访问，shipmentIndex 和 visitRequestIndex 必须在范围内。
  • 一次只能在一条路线中引用一次配送。
  • 取件配送型货件的取件必须在配送之前完成。
  • 不得对同一批次货物执行超过一次取货替代方案或送货替代方案。
  • 对于所有路线，时间都在增加（即vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime）。
  • 只能使用允许的车辆进行配送。如果 Shipment.allowed_vehicle_indices 为空或其 vehicleIndex 包含在 Shipment.allowed_vehicle_indices 中，则允许相应车辆。

如果注入的解不可行，系统不一定会返回验证错误，而是可能会返回指示不可行的错误。
injectedSolutionConstraint

object (InjectedSolutionConstraint)

限制优化算法，使其找到与之前解决方案类似的最终解决方案。例如，这可用于冻结已完成或将要完成但不得修改的部分路线。

如果注入的解不可行，系统不一定会返回验证错误，而是可能会返回指示不可行的错误。
refreshDetailsRoutes[]

object (ShipmentRoute)

如果不为空，则会刷新给定的路线，而不会修改其基础访问序列或出行时间：只会更新其他详细信息。这并不能解决模型。

截至 2020 年 11 月，此方法仅填充非空路线的折线，并且要求 populatePolylines 为 true。

传入路线的 routePolyline 字段可能与路线 transitions 不一致。

此字段不得与 injectedFirstSolutionRoutes 或 injectedSolutionConstraint 一起使用。

Shipment.ignore 和 Vehicle.ignore 对行为没有影响。无论是否忽略相关货件或车辆，系统仍会在所有非空路线中的所有访问之间填充多段线。
interpretInjectedSolutionsUsingLabels

boolean

如果为 true：

此解释适用于 injectedFirstSolutionRoutes、injectedSolutionConstraint 和 refreshDetailsRoutes 字段。如果自创建解决方案以来，请求中的配送或车辆指数发生了变化（可能是因为从请求中移除了配送或车辆，或者向请求中添加了配送或车辆），则可以使用此参数。

如果为 true，则以下类别的标签在其类别中最多只能出现一次：

如果注入的解决方案中的 vehicleLabel 与请求车辆不对应，则会从解决方案中移除相应路线及其访问。如果注入的解决方案中的 shipmentLabel 与请求的配送不对应，则会从解决方案中移除相应拜访。如果注入的解决方案中的 SkippedShipment.label 与请求的货件不对应，则从解决方案中移除 SkippedShipment。

从注入的解决方案中移除路线访问或整个路线可能会影响隐含的限制，从而导致解决方案发生变化、出现验证错误或不可行。

注意：调用方必须确保每个 Vehicle.label（相应地，Shipment.label) 用于在两个相关请求中唯一标识车辆（相应地，货物）实体：生成注入解决方案中所用 OptimizeToursResponse 的过去请求，以及包含注入解决方案的当前请求。上述唯一性检查不足以保证满足此要求。
considerRoadTraffic

boolean

在计算 ShipmentRoute 字段 Transition.travel_duration、Visit.start_time 和 vehicleEndTime 时，在设置 ShipmentRoute.has_traffic_infeasibilities 字段时，以及在计算 OptimizeToursResponse.total_cost 字段时，考虑流量估算。
populatePolylines

boolean

如果为 true，则会在响应 ShipmentRoute 中填充折线。
populateTransitionPolylines

boolean

如果为 true，则会在响应 ShipmentRoute.transitions 中填充折线和路线令牌。
allowLargeDeadlineDespiteInterruptionRisk

boolean

如果设置了此参数，则请求的截止时间（请参阅 https://grpc.io/blog/deadlines）最长可达 60 分钟。否则，最长截止期限仅为 30 分钟。请注意，长时间运行的请求被中断的风险会明显更高（但仍很小）。
useGeodesicDistances

boolean

如果为 true，则使用测地线距离（而非 Google 地图距离）计算出行距离，并使用测地线距离和由 geodesicMetersPerSecond 定义的速度计算出行时间。
label

string

可用于标识此请求的标签，会在 OptimizeToursResponse.request_label 中报告。
geodesicMetersPerSecond

number

当 useGeodesicDistances 为 true 时，必须设置此字段，用于定义应用于计算出行时间的行驶速度。其值必须至少为 1.0 米/秒。
maxValidationErrors

integer

截断返回的验证错误数量。除非 solvingMode=VALIDATE_ONLY，否则这些错误通常会作为 BadRequest 错误详情 (https://cloud.google.com/apis/design/errors#error_details) 附加到 INVALID_ARGUMENT 错误载荷。请参阅 OptimizeToursResponse.validation_errors 字段。此值默认为 100，上限为 10,000。

响应正文

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

授权范围

需要以下 OAuth 范围：

  • https://www.googleapis.com/auth/cloud-platform

IAM 权限

需要拥有 parent 资源的以下 IAM 权限：

  • routeoptimization.locations.use

如需了解详情，请参阅 IAM 文档。