Method: projects.locations.optimizeTours
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
发送包含 ShipmentModel
的 OptimizeToursRequest
,并返回包含 ShipmentRoute
的 OptimizeToursResponse
,这些 ShipmentRoute
是车辆执行的一组路线,可最大限度地降低总费用。
ShipmentModel
模型主要由需要执行的 Shipment
和可用于传输 Shipment
的 Vehicle
组成。ShipmentRoute
会将 Shipment
分配给 Vehicle
。更具体地说,它们会为每辆车分配一系列 Visit
,其中 Visit
对应于 VisitRequest
,即 Shipment
的接送点。
目标是为 Vehicle
分配 ShipmentRoute
,以尽可能降低总费用,其中费用在 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
如果为真:
这种解释适用于 injectedFirstSolutionRoutes 、injectedSolutionConstraint 和 refreshDetailsRoutes 字段。如果自解决方案创建后,请求中的运单或车辆索引发生了变化(可能是因为运单或车辆已从该请求中移除或添加到该请求中),则可以使用此参数。 如果为 true,以下类别中的标签必须在其类别中最多出现一次:
如果注入的解决方案中的 vehicleLabel 与请求车辆不对应,则系统会从解决方案中移除相应的路线及其到访记录。如果注入的解决方案中的 shipmentLabel 与运单请求不相符,系统会从解决方案中移除相应的访问。如果注入的解决方案中的 SkippedShipment.label 与运单请求不相符,系统会将 SkippedShipment 从解决方案中移除。 从注入的解决方案中移除路线访问或整个路线可能会影响隐式约束条件,从而导致解决方案发生变化、出现验证错误或不可行。 注意:调用方必须确保每个 Vehicle.label (resp.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
如果设置此值,则请求可以设置最长 60 分钟的截止期限(请参阅 https://grpc.io/blog/deadlines)。否则,最长期限只有 30 分钟。请注意,长期请求存在的中断风险要大得多(但也很小)。
|
useGeodesicDistances |
boolean
如果为 true,则将使用测地距离(而非 Google 地图距离)计算行程距离,并使用测地距离和 geodesicMetersPerSecond 定义的速度计算行程时间。
|
label |
string
可用于识别此请求的标签,会在 OptimizeToursResponse.request_label 中报告。
|
geodesicMetersPerSecond |
number
当 useGeodesicDistances 为 true 时,必须设置此字段并定义用于计算行程时间的速度。其值必须至少为 1.0 米/秒。
|
maxValidationErrors |
integer
截断返回的验证错误数。这些错误通常作为 BadRequest 错误详情 (https://cloud.google.com/apis/design/errors#error_details) 附加到 INVALID_ARGUMENT 错误负载,除非 SolveMode=VALIDATE_ONLY: 请参阅 OptimizeToursResponse.validation_errors 字段。此值的默认值为 100,上限为 10,000。
|
响应正文
如果成功,则响应正文包含一个 OptimizeToursResponse
实例。
授权范围
需要以下 OAuth 范围:
https://www.googleapis.com/auth/cloud-platform
IAM 权限
需要拥有 parent
资源的以下 IAM 权限:
routeoptimization.locations.use
如需了解详情,请参阅 IAM 文档。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-31。
[null,null,["最后更新时间 (UTC):2025-08-31。"],[[["\u003cp\u003eSends an \u003ccode\u003eOptimizeToursRequest\u003c/code\u003e and returns an \u003ccode\u003eOptimizeToursResponse\u003c/code\u003e containing optimized \u003ccode\u003eShipmentRoute\u003c/code\u003es for a given \u003ccode\u003eShipmentModel\u003c/code\u003e and \u003ccode\u003eVehicle\u003c/code\u003es.\u003c/p\u003e\n"],["\u003cp\u003eThe service aims to minimize the total cost of routes by assigning \u003ccode\u003eShipment\u003c/code\u003es to \u003ccode\u003eVehicle\u003c/code\u003es and optimizing their \u003ccode\u003eVisit\u003c/code\u003e sequences.\u003c/p\u003e\n"],["\u003cp\u003eRequest body includes parameters to guide the optimization process such as timeout, model, solving mode, search mode, and constraints.\u003c/p\u003e\n"],["\u003cp\u003eThe response contains the optimized routes, including details like polylines, travel durations, and total cost.\u003c/p\u003e\n"],["\u003cp\u003eRequires the \u003ccode\u003ehttps://www.googleapis.com/auth/cloud-platform\u003c/code\u003e OAuth scope and \u003ccode\u003erouteoptimization.locations.use\u003c/code\u003e IAM permission.\u003c/p\u003e\n"]]],["This content describes the `OptimizeTours` API, which optimizes routes for shipments using vehicles. A `POST` request is sent to `https://routeoptimization.googleapis.com/v1/{parent=projects/*/locations/*}:optimizeTours`. The request body includes a `ShipmentModel` specifying shipments and vehicles. The API then generates an `OptimizeToursResponse` with `ShipmentRoute`s, assigning `Visit`s (pickups/deliveries) to each vehicle to minimize total cost. Optional parameters allow traffic consideration, polyline population, and injected solution constraints. Authorization requires cloud platform scope and IAM permissions.\n"],null,[]]