Package google.maps.routeoptimization.v1

索引

RouteOptimization

用于优化车辆行程的服务。

某些类型字段的有效性：

  • google.protobuf.Timestamp
    • 时间采用 Unix 时间格式：自 1970-01-01T00:00:00+00:00 以来的秒数。
    • 秒数必须介于 [0, 253402300799] 之间，即介于 [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00] 之间。
    • 纳诺必须未设置或设置为 0。
  • google.protobuf.Duration
    • 秒数必须介于 [0, 253402300799] 之间，即介于 [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00] 之间。
    • 纳诺必须未设置或设置为 0。
  • google.type.LatLng
    • 纬度必须在 [-90.0, 90.0] 范围内。
    • 经度必须在 [-180.0, 180.0] 范围内。
    • 纬度和经度中至少有一个不能为零。
BatchOptimizeTours

rpc BatchOptimizeTours(BatchOptimizeToursRequest) returns (Operation)

以批处理方式优化一个或多个 OptimizeToursRequest 消息的车辆游览路线。

此方法是一项长时间运行的操作 (LRO)。优化输入（OptimizeToursRequest 消息）和输出（OptimizeToursResponse 消息）以用户指定的格式从 Cloud Storage 读取和写入。与 OptimizeTours 方法类似，每个 OptimizeToursRequest 都包含一个 ShipmentModel，并返回一个包含 ShipmentRoute 字段的 OptimizeToursResponse，这些字段是一组要由车辆执行的路线，可最大限度地降低总体成本。

用户可以轮询 operations.get 以检查 LRO 的状态：

如果 LRO done 字段为 false，则表示至少有一个请求仍在处理中。其他请求可能已成功完成，其结果可在 Cloud Storage 中查看。

如果 LRO 的 done 字段为 true，则表示所有请求都已处理完毕。所有成功处理的请求的结果都可在 Cloud Storage 中找到。所有失败的请求的结果都无法在 Cloud Storage 中找到。如果设置了 LRO 的 error 字段，则表示其中包含某个失败请求的错误。

授权范围

需要以下 OAuth 范围：

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

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

  • routeoptimization.operations.create

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

rpc OptimizeTours(OptimizeToursRequest) returns (OptimizeToursResponse)

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

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

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

授权范围

需要以下 OAuth 范围：

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

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

  • routeoptimization.locations.use

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

rpc OptimizeToursLongRunning(OptimizeToursRequest) returns (Operation)

这是 OptimizeTours 方法的一种变体，旨在优化具有较大超时值的情况。对于耗时超过几分钟的优化，应优先使用此方法，而不是 OptimizeTours 方法。

返回的 long-running operation (LRO) 的名称格式为 <parent>/operations/<operation_id>，可用于跟踪计算进度。metadata 字段类型为 OptimizeToursLongRunningMetadata。如果成功，response 字段类型为 OptimizeToursResponse。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/otlr/make-request。

授权范围

需要以下 OAuth 范围：

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

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

  • routeoptimization.operations.create

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

rpc OptimizeToursUri(OptimizeToursUriRequest) returns (Operation)

这是 OptimizeToursLongRunning 方法的一种变体，旨在针对具有较大超时值和较大输入/输出大小的情况进行优化。

客户端指定存储在 Google Cloud Storage 中的 OptimizeToursRequest 的 URI，服务器将 OptimizeToursResponse 写入客户端指定的 Google Cloud Storage URI。

对于耗时超过几分钟且输入/输出大小超过 8MB 的优化，应优先使用此方法，不过它也可用于耗时较短且输入/输出较小的优化。OptimizeTours

返回的 long-running operation (LRO) 的名称格式为 <parent>/operations/<operation_id>，可用于跟踪计算进度。metadata 字段类型为 OptimizeToursLongRunningMetadata。如果成功，response 字段类型为 OptimizeToursUriResponse。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/otlr/make-request。

授权范围

需要以下 OAuth 范围：

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

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

  • routeoptimization.operations.create

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

AggregatedMetrics

所有 Transition 和/或 Visit（或所有 ShipmentRoute）元素的 ShipmentRoute（或 OptimizeToursResponse）的汇总指标。

字段
performed_shipment_count

int32

执行的配送次数。请注意，取件和送件配对仅计为一次。
travel_duration

Duration

路线或解决方案的总行程时长。
wait_duration

Duration

路线或解决方案的总等待时长。
delay_duration

Duration

路线或解决方案的总延迟时长。
break_duration

Duration

路线或解决方案的总中断时长。
visit_duration

Duration

路线或解决方案的总访问时长。
total_duration

Duration

总时长应等于上述所有时长的总和。对于路线，它还对应于：

[ShipmentRoute.vehicle_end_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_end_time] - [ShipmentRoute.vehicle_start_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_start_time]
travel_distance_meters

double

路线或解决方案的总出行距离。
max_loads

map<string, VehicleLoad>

整个路线（相应地，解决方案）上达到的最大负荷，针对该路线（相应地，解决方案）上的每个量计算，计算方式为所有 Transition.vehicle_loads（相应地，ShipmentRoute.metrics.max_loads。
performed_mandatory_shipment_count

int32

执行的强制性配送次数。

实验性：此字段的行为或存在状态将来可能会发生变化。
performed_shipment_penalty_cost_sum

double

已完成的货件的 Shipment.penalty_cost 之和。

实验性：此字段的行为或存在状态将来可能会发生变化。

BatchOptimizeToursMetadata

此类型没有字段。

针对 BatchOptimizeToursRequest 调用的操作元数据。

BatchOptimizeToursRequest

请求以异步操作方式批量优化行程。每个输入文件应包含一个 OptimizeToursRequest，每个输出文件将包含一个 OptimizeToursResponse。该请求包含用于读取/写入和解析文件的信息。所有输入和输出文件都应位于同一项目下。

字段
parent

string

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

格式：

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

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

AsyncModelConfig

必需。每个购买模型的输入/输出信息，例如文件路径和数据格式。

AsyncModelConfig

用于异步求解一个优化模型的信息。

字段
display_name

string

可选。用户定义的模型名称，可供用户用作别名来跟踪模型。
input_config

InputConfig

必需。有关输入模型的信息。
output_config

OutputConfig

必需。所需的输出位置信息。

BatchOptimizeToursResponse

此类型没有字段。

对 BatchOptimizeToursRequest 的响应。此响应会在操作完成后返回到长时间运行的操作中。

BreakRule

用于为车辆生成时间中断（例如午休）的规则。中断是指车辆在当前位置保持空闲且无法执行任何访问的连续时间段。中断可能发生在：

  • 在两次访问之间的行程期间（包括访问之前或之后的这段时间，但不包括访问期间），在这种情况下，它会延长两次访问之间的相应运送时间，
  • 或在车辆启动之前（车辆可能不会在休息期间启动），在这种情况下，它不会影响车辆启动时间。
  • 或车辆结束时间之后（同样，使用车辆结束时间）。
字段
break_requests[]

BreakRequest

插播广告的顺序。请参阅 BreakRequest 消息。
frequency_constraints[]

FrequencyConstraint

可能适用多个 FrequencyConstraint。它们必须全部由相应 BreakRule 的 BreakRequest 满足。请参阅 FrequencyConstraint。

BreakRequest

必须预先知道适用于每辆车的休息顺序（即休息次数和顺序）。重复的 BreakRequest 定义了该序列，以及它们必须发生的顺序。它们的时间窗口（earliest_start_time / latest_start_time）可能会重叠，但必须与顺序兼容（系统会进行检查）。

字段
earliest_start_time

Timestamp

必需。休止开始时间的下限（含）。
latest_start_time

Timestamp

必需。休止开始时间的上限（含）。
min_duration

Duration

必需。休息时长的下限。必须为正值。

FrequencyConstraint

还可以通过强制执行最小中断频率来进一步限制上述指定的中断频率和时长，例如“每 12 小时必须至少有 1 小时的中断”。假设这可以解释为“在任何 12 小时的滑动时间窗口内，必须至少有一次至少 1 小时的中断”，那么该示例将转换为以下 FrequencyConstraint：

{
   min_break_duration { seconds: 3600 }         # 1 hour.
   max_inter_break_duration { seconds: 39600 }  # 11 hours (12 - 1 = 11).
}

解决方案中休息的时间和时长将遵守所有此类限制，以及 BreakRequest 中已指定的时间窗口和最短时长。

实际上，FrequencyConstraint 可能适用于非连续休息时间。例如，以下时间表符合“每 12 小时休息 1 小时”的示例：

  04:00 vehicle start
   .. performing travel and visits ..
  09:00 1 hour break
  10:00 end of the break
   .. performing travel and visits ..
  12:00 20-min lunch break
  12:20 end of the break
   .. performing travel and visits ..
  21:00 1 hour break
  22:00 end of the break
   .. performing travel and visits ..
  23:59 vehicle end
字段
min_break_duration

Duration

必需。相应限制的广告插播时长下限。非负。请参阅 FrequencyConstraint 的说明。
max_inter_break_duration

Duration

必需。路线中任何时间间隔的最大允许跨度，该时间间隔不包含至少部分 duration >= min_break_duration 的休息时间。必须为正值。

DataFormat

输入和输出文件的数据格式。

枚举
DATA_FORMAT_UNSPECIFIED 值无效，格式不得为 UNSPECIFIED。
JSON JavaScript 对象表示法。
PROTO_TEXT Protocol Buffers 文本格式。请参阅 https://protobuf.dev/reference/protobuf/textformat-spec/

DistanceLimit

用于定义可行驶的最大距离的限制。可以是硬性限制，也可以是软性限制。

如果定义了软限制，则必须定义 soft_max_meters 和 cost_per_kilometer_above_soft_max，且这两个值必须为非负数。

字段
max_meters

int64

一种硬性限制，用于将距离限制为最多 max_meters。限值必须是非负数。
soft_max_meters

int64

一种不强制执行最大距离限制的软限制，但如果违反该限制，则会产生费用，该费用会与模型中定义的其他费用相加，单位相同。

如果定义了 soft_max_meters，则该值必须小于 max_meters 且必须为非负数。
cost_per_kilometer_below_soft_max

double

每公里产生的费用，最高可增加到 soft_max_meters，公式如下：

  min(distance_meters, soft_max_meters) / 1000.0 *
  cost_per_kilometer_below_soft_max.

route_distance_limit 不支持此费用。
cost_per_kilometer_above_soft_max

double

如果距离超过 soft_max_meters 限制，则每公里产生的费用。如果距离未超过限制，则额外费用为 0；否则，用于计算费用的公式如下：

  (distance_meters - soft_max_meters) / 1000.0 *
  cost_per_kilometer_above_soft_max.

费用必须为非负值。

GcsDestination

将写入输出文件的 Google Cloud Storage 位置。

字段
uri

string

必需。Google Cloud Storage URI。

GcsSource

将从中读取输入文件的 Google Cloud Storage 位置。

字段
uri

string

必需。Google Cloud Storage 对象的 URI，格式为 gs://bucket/path/to/object。

InjectedSolutionConstraint

注入到请求中的解决方案，包括有关哪些拜访必须受到限制以及必须如何受到限制的信息。

字段
routes[]

ShipmentRoute

要注入的解决方案的路线。原始解决方案中的某些路线可能会被省略。路线和跳过的配送必须满足 injected_first_solution_routes 中列出的基本有效性假设。
skipped_shipments[]

SkippedShipment

要注入的解决方案的跳过发货。部分可能已从原始解决方案中省略。请参阅 routes 字段。
constraint_relaxations[]

ConstraintRelaxation

针对零个或多个车辆组，指定何时以及在多大程度上放宽限制。如果此字段为空，则所有非空车辆路线都将受到完全限制。

ConstraintRelaxation

对于一组车辆，指定在哪些阈值下，访问次数限制将放宽到哪个级别。skipped_shipment 字段中列出的配送会被限制为跳过，即无法执行。

字段
relaxations[]

Relaxation

将应用于 vehicle_indices 中有车辆的路线上的所有访问的访问限制放宽。
vehicle_indices[]

int32

指定访问限制 relaxations 所适用的车辆指数。如果为空，则视为默认值，并且 relaxations 适用于其他 constraint_relaxations 中未指定的所有车辆。最多只能有一个默认值，即最多只能有一个约束放宽字段为空 vehicle_indices。即使在多个 constraint_relaxations 中，车辆指数也只能列出一次。

如果 interpret_injected_solutions_using_labels 为 true，则车辆索引的映射方式与 ShipmentRoute.vehicle_index 相同（请参阅 fields 注释）。

娱乐

如果 relaxations 为空，则 routes 上所有访问的开始时间和顺序都受到完全限制，并且不得向这些路线插入或添加新的访问。此外，除非车辆为空（即没有访问，并且模型中 used_if_route_is_empty 设置为 false），否则 routes 中车辆的开始时间和结束时间都受到完全限制。

relaxations(i).level 指定应用于满足以下条件的访问会话 #j 的限制放宽级别：

  • route.visits(j).start_time >= relaxations(i).threshold_time 和
  • j + 1 >= relaxations(i).threshold_visit_count

同样，如果车辆启动满足以下条件，则放松到 relaxations(i).level：

  • vehicle_start_time >= relaxations(i).threshold_time 和
  • relaxations(i).threshold_visit_count == 0，如果满足以下条件，则车辆端放宽至 relaxations(i).level：
  • vehicle_end_time >= relaxations(i).threshold_time 和
  • route.visits_size() + 1 >= relaxations(i).threshold_visit_count

如果访问满足 threshold_visit_count 或 threshold_time，则应用放松级别。为此，请添加两个具有相同 level 的 relaxations：一个仅设置了 threshold_visit_count，另一个仅设置了 threshold_time。如果某次访问满足多个 relaxations 的条件，系统会应用最宽松的级别。因此，从车辆启动到按顺序访问路线中的各个地点，再到车辆结束，放松程度会越来越高，也就是说，放松程度会随着路线的推进而保持不降。

不满足任何 relaxations 的阈值条件的路线访问的时间和顺序完全受限，并且不得在这些序列中插入任何访问。此外，如果车辆的开始或结束时间不满足任何放宽条件，则时间是固定的，除非车辆为空。

字段
level

Level

当满足 threshold_time 及之后和至少 threshold_visit_count 的条件时应用的约束放宽级别。
threshold_time

Timestamp

可应用放松措施 level 的时间或之后的时间。
threshold_visit_count

int32

可应用放松level的访问次数（从第几次访问开始）。如果 threshold_visit_count 为 0（或未设置），则可在车辆启动时直接应用 level。

如果值为 route.visits_size() + 1，则 level 只能应用于车辆端。如果大于 route.visits_size() + 1，则不会为相应路线应用 level。

级别

表示不同的约束放宽级别，当访问满足阈值条件时，系统会应用这些级别以及后续级别。

以下枚举按宽松程度递增的顺序排列。

枚举
LEVEL_UNSPECIFIED

隐式默认放松级别：不放松任何限制，即所有访问都完全受限。

不得在 level 中明确使用此值。
RELAX_VISIT_TIMES_AFTER_THRESHOLD 到访开始时间和车辆开始/结束时间将放宽，但每次到访仍与同一车辆相关联，并且必须遵守到访顺序：不得在它们之间或之前插入任何到访。
RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD 与 RELAX_VISIT_TIMES_AFTER_THRESHOLD 相同，但访问序列也放宽了：访问只能由相应车辆执行，但可能会变为未执行。
RELAX_ALL_AFTER_THRESHOLD 与 RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD 相同，但车辆也处于宽松状态：在阈值时间或之后，访问完全免费，并且可能会变为未执行。

InputConfig

为 [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours] 指定输入。

字段
data_format

DataFormat

必需。输入数据格式。
联合字段 source。必需。source 只能是下列其中一项：
gcs_source

GcsSource

Google Cloud Storage 位置。这必须是单个对象（文件）。

位置

封装位置信息（地理点和可选的航向）。

字段
lat_lng

LatLng

途经点的地理坐标。
heading

int32

与交通流量方向相关的罗盘方向。此值用于指定上下车时要使用的道路一侧。航向值可以介于 0 到 360 之间，其中 0 表示正北航向，90 表示正东航向，依此类推。

OptimizeToursLongRunningMetadata

此类型没有字段。

针对 OptimizeToursLongRunning 调用的操作元数据。

OptimizeToursRequest

要提供给行程优化求解器的请求，用于定义要解决的配送模型以及优化参数。

字段
parent

string

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

格式：

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

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

Duration

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

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

ShipmentModel

要解决的货件模型。
solving_mode

SolvingMode

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

SearchMode

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

ShipmentRoute

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

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

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

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

如果注入的解决方案不可行，则不一定会返回验证错误，而是可能会返回指示不可行的错误。
injected_solution_constraint

InjectedSolutionConstraint

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

如果注入的解决方案不可行，则不一定会返回验证错误，而是可能会返回指示不可行的错误。
refresh_details_routes[]

ShipmentRoute

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

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

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

此字段不得与 injected_first_solution_routes 或 injected_solution_constraint 一起使用。

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

bool

如果为 true：

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

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

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

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

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

bool

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

bool

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

bool

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

bool

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

bool

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

string

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

double

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

int32

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

SearchMode

用于定义搜索行为的模式，可权衡延迟时间和解决方案质量。在所有模式下，系统都会强制执行全局请求截止时间。

枚举
SEARCH_MODE_UNSPECIFIED 未指定的搜索模式，相当于 RETURN_FAST。
RETURN_FAST 在找到第一个不错的解决方案后停止搜索。
CONSUME_ALL_AVAILABLE_TIME 花费所有可用时间来寻找更好的解决方案。

SolvingMode

定义求解器应如何处理请求。在 VALIDATE_ONLY 以外的所有模式下，如果请求无效，您将收到 INVALID_REQUEST 错误。请参阅 max_validation_errors 以限制返回的错误数量。

枚举
DEFAULT_SOLVE 求解模型。警告可能会在 [OptimizeToursResponse.validation_errors][google.cloud.optimization.v1.OptimizeToursResponse.validation_errors] 中发出。
VALIDATE_ONLY 仅验证模型而不求解：尽可能多地填充 OptimizeToursResponse.validation_errors。
DETECT_SOME_INFEASIBLE_SHIPMENTS

仅填充 OptimizeToursResponse.validation_errors 或 OptimizeToursResponse.skipped_shipments，实际上并未解决请求的其余部分（响应中未设置 status 和 routes）。如果检测到 injected_solution_constraint 路线中存在不可行性，则这些不可行性会填充到 OptimizeToursResponse.validation_errors 字段中，而 OptimizeToursResponse.skipped_shipments 字段则留空。

重要提示：并非所有不可行的配送都会在此处返回，只有在预处理期间检测为不可行的配送才会在此处返回。
TRANSFORM_AND_RETURN_REQUEST

此模式仅在 ShipmentModel.objectives 不为空时有效。系统不会求解请求，只会验证请求并填充与指定目标对应的费用。另请参阅 ShipmentModel.objectives 的文档。生成的请求将作为 OptimizeToursResponse.processed_request 返回。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。

OptimizeToursResponse

解决旅游优化问题后的响应，其中包含每辆车行驶的路线、已跳过的配送以及解决方案的总费用。

字段
routes[]

ShipmentRoute

为每辆车计算的路线；第 i 条路线对应于模型中的第 i 辆车。
request_label

string

OptimizeToursRequest.label 的副本（如果请求中指定了标签）。
skipped_shipments[]

SkippedShipment

所有跳过的配送的列表。
validation_errors[]

OptimizeToursValidationError

我们能够独立检测到的所有验证错误的列表。请参阅 OptimizeToursValidationError 消息的“MULTIPLE ERRORS”说明。如果 solving_mode 为 DEFAULT_SOLVE，则此列表将包含警告，而不是错误。
processed_request

OptimizeToursRequest

在某些情况下，我们会先修改传入的请求（即添加费用），然后再解决问题。如果 solving_mode == TRANSFORM_AND_RETURN_REQUEST，则在此处返回修改后的请求。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。
metrics

Metrics

此解决方案的时长、距离和使用情况指标。

指标

汇总了所有路线的总体指标。

字段
aggregated_route_metrics

AggregatedMetrics

按路线汇总。每个指标都是所有同名 ShipmentRoute.metrics 字段的总和（或最大值，对于负载而言）。
skipped_mandatory_shipment_count

int32

跳过的强制性配送次数。
used_vehicle_count

int32

使用的车辆数量。注意：如果车辆路线为空且 Vehicle.used_if_route_is_empty 为 true，则车辆会被视为已使用。
earliest_vehicle_start_time

Timestamp

二手车的最早开始时间，计算方式为所有二手车的 ShipmentRoute.vehicle_start_time 的最小值。
latest_vehicle_end_time

Timestamp

二手车的最新结束时间，计算方式为所有二手车的 ShipmentRoute.vehicle_end_time 中的最大值。
costs

map<string, double>

解决方案的费用，按与费用相关的请求字段细分。键是相对于输入 OptimizeToursRequest 的 proto 路径，例如“model.shipments.pickups.cost”，值是相应费用字段生成的总费用，汇总了整个解决方案的费用。换句话说，costs["model.shipments.pickups.cost"] 是解决方案中所有取货费用的总和。模型中定义的所有费用都会在此处详细报告，但与 TransitionAttributes 相关的费用除外，这些费用自 2022 年 1 月起仅以汇总方式报告。
total_cost

double

解决方案的总费用。费用映射中所有值的总和。

OptimizeToursUriMetadata

此类型没有字段。

针对 OptimizeToursUri 调用的操作元数据。

OptimizeToursUriRequest

OptimizeToursUri 方法使用的请求。

字段
parent

string

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

格式：

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

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

Uri

必需。包含 OptimizeToursRequest 的 Cloud Storage 对象的 URI。
output

Uri

必需。将包含 OptimizeToursResponse 的 Cloud Storage 对象的 URI。

OptimizeToursUriResponse

OptimizeToursUri 方法返回的响应。

字段
output

Uri

可选。包含 OptimizeToursResponse（编码为 JSON 或 textproto）的 Cloud Storage 对象的 URI。如果对象以 JSON 格式编码，则对象名称的扩展名将为 .json。如果对象以 textproto 格式编码，则对象名称的扩展名将为 .txtpb。

资源的 crc32_checksum 可用于验证资源的内容是否未被修改。

OptimizeToursValidationError

描述验证 OptimizeToursRequest 时遇到的错误或警告。

字段
code

int32

验证错误由始终存在的 (code, display_name) 对定义。

此部分后面的字段提供了有关错误的更多背景信息。

多个错误：如果存在多个错误，验证过程会尝试输出其中的几个错误。与编译器类似，这是一个不完善的过程。有些验证错误是“致命”的，这意味着它们会停止整个验证过程。display_name="UNSPECIFIED" 错误就是这种情况。有些错误可能会导致验证过程跳过其他错误。

稳定性：code 和 display_name 应该非常稳定。但随着时间的推移，可能会出现新的代码和显示名称，这可能会导致给定的（无效）请求产生不同的 (code, display_name) 对，因为新错误隐藏了旧错误。例如，请参阅“多个错误”。
display_name

string

错误的显示名称。
fields[]

FieldReference

错误上下文可能涉及 0 个、1 个（大多数情况下）或多个字段。例如，引用车辆 4 和货件 2 的首次取货可以按如下方式进行：

fields { name: "vehicles" index: 4}
fields { name: "shipments" index: 2 sub_field {name: "pickups" index: 0} }

不过请注意，对于给定的错误代码，fields 的基数不应发生变化。
error_message

string

用于描述错误的直观易懂的字符串。code 和 error_message 之间存在一对一的映射关系（当代码不为“UNSPECIFIED”时）。

稳定性：不稳定：与给定 code 关联的错误消息可能会随时间变化（希望是变得更清晰）。请改用 display_name 和 code。
offending_values

string

可能包含相应字段的值。此属性并非始终可用。您绝对不应依赖此属性，而应仅将其用于手动调试模型。

FieldReference

指定验证错误的上下文。FieldReference 始终是指此文件中的给定字段，并遵循相同的层次结构。例如，我们可以使用以下方式指定车辆 5 的 start_time_windows 的元素 2：

name: "vehicles" index: 5 sub_field { name: "end_time_windows" index: 2 }

不过，我们会省略 OptimizeToursRequest 或 ShipmentModel 等顶级实体，以免消息过于拥挤。

字段
name

string

字段名称，例如“vehicles”。
sub_field

FieldReference

递归嵌套的子字段（如果需要）。

联合字段 index_or_key。

index_or_key 只能是下列其中一项：
index

int32

如果字段重复，则为字段的索引。
key

string

如果相应字段是映射，则为键。

OutputConfig

为 [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours] 结果指定目的地。

字段
data_format

DataFormat

必需。输出数据格式。
联合字段 destination。必需。destination 只能是下列其中一项：
gcs_destination

GcsDestination

要向其中写入输出的 Google Cloud Storage 位置。

RouteModifiers

封装了一组在计算车辆路线时要满足的可选条件。这与 Google Maps Platform Routes Preferred API 中的 RouteModifiers 类似；请参阅：https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteModifiers。

字段
avoid_tolls

bool

指定是否尽可能避开收费公路。系统会优先选择不包含收费公路的路线。仅适用于机动车出行方式。
avoid_highways

bool

指定是否尽可能避开高速公路。系统会优先选择不包含高速公路的路线。仅适用于机动车出行方式。
avoid_ferries

bool

指定是否在合理的情况下避开轮渡。系统会优先选择不包含轮渡行程的路线。仅适用于机动出行方式。
avoid_indoor

bool

可选。指定是否在合理的情况下避免室内导航。系统会优先选择不包含室内导航的路线。仅适用于 WALKING 出行模式。

发货

单个商品的运输，从取货点到送货点。若要将运输视为已完成，必须有唯一的车辆访问其中一个取货点（并相应地减少其剩余容量），然后稍后访问其中一个送货点（并相应地重新增加其剩余容量）。

字段
display_name

string

货件的用户自定义显示名称。不得超过 63 个字符，可以使用 UTF-8 字符。
pickups[]

VisitRequest

与相应配送相关联的一组自提替代方案。如果未指定，车辆只需前往与配送对应的位置。
deliveries[]

VisitRequest

与相应配送相关联的一组配送替代方案。如果未指定，车辆只需前往与取货对应的位置。
load_demands

map<string, Load>

货件的装载需求（例如重量、体积、托盘数量等）。映射中的键应是描述相应负载类型的标识符，最好还包含单位。例如：“weight_kg”“volume_gallons”“pallet_count”等。如果给定键未出现在映射中，则相应载荷将被视为 null。
allowed_vehicle_indices[]

int32

可能执行相应配送的一组车辆。如果为空，则所有车辆都可以执行该操作。车辆由其在 ShipmentModel 的 vehicles 列表中的索引给出。
costs_per_vehicle[]

double

指定每辆车在运送相应货物时产生的费用。如果指定，则必须具有以下任一属性：

  • 与 costs_per_vehicle_indices 的元素数量相同。costs_per_vehicle[i] 对应于模型的车辆 costs_per_vehicle_indices[i]。
  • 与模型中的车辆数量相同的元素数量。第 i 个元素对应于相应型号的第 i 辆车。

这些费用必须与 penalty_cost 的单位相同，且不得为负数。如果没有此类费用，请将此字段留空。
costs_per_vehicle_indices[]

int32

costs_per_vehicle 适用的车辆的索引。如果非空，则必须与 costs_per_vehicle 具有相同数量的元素。车辆索引不得多次指定。如果车辆被排除在 costs_per_vehicle_indices 之外，则其费用为零。
pickup_to_delivery_absolute_detour_limit

Duration

指定与从取货地到送货地的最短路径相比，最长的绝对绕行时间。如果指定，则必须为非负值，并且相应配送必须包含至少一个取货地和一个送货地。

例如，假设 t 是从所选自提替代方案直接前往所选送货替代方案所需的最短时间。那么，设置 pickup_to_delivery_absolute_detour_limit 会强制执行以下条件：

start_time(delivery) - start_time(pickup) <=
t + pickup_to_delivery_absolute_detour_limit

如果同一批货件同时指定了相对限制和绝对限制，则对于每个可能的取货/送货对，系统会使用限制更严格的那个。截至 2017 年 10 月，只有在出行时长不取决于车辆时，系统才支持绕行。
pickup_to_delivery_time_limit

Duration

指定从取货开始到送货开始的运输时间上限。如果指定，则必须为非负值，并且相应配送必须至少包含取货和送货。此属性不取决于为取货和送货选择的替代方案，也不取决于车辆速度。此属性可以与绕路限制上限一起指定：解决方案将同时满足这两项规范。
shipment_type

string

非空字符串，用于指定相应货件的“类型”。此功能可用于定义 shipment_types 之间的不兼容性或要求（请参阅 ShipmentModel 中的 shipment_type_incompatibilities 和 shipment_type_requirements）。

与为单次访问指定的 visit_types 不同：属于同一批次的所有取货/送货共用同一个 shipment_type。
label

string

为相应配送指定标签。此标签会在相应 ShipmentRoute.Visit 的 shipment_label 中报告。
ignore

bool

如果为 true，则跳过相应配送，但不应用 penalty_cost。

如果模型中存在任何 shipment_type_requirements，忽略配送会导致验证错误。

允许忽略在 injected_first_solution_routes 或 injected_solution_constraint 中执行的配送；求解器会从执行路线中移除相关的取货/送货访问。引用被忽略配送的 precedence_rules 也会被忽略。
penalty_cost

double

如果未完成配送，此罚款将添加到路线的总费用中。如果某个配送方案的取货和送货替代方案之一被访问，则该配送方案被视为已完成。费用可以采用模型中所有其他与费用相关的字段所用的相同单位表示，并且必须为正值。

重要提示：如果未指定此罚款，则视为无限期，即必须完成配送。
pickup_to_delivery_relative_detour_limit

double

指定与从取货地到送货地的最短路径相比，相对绕行时间的最大值。如果指定，则必须为非负值，并且相应配送必须包含至少一个取货地和一个送货地。

例如，假设 t 是从所选自提替代方案直接前往所选送货替代方案所需的最短时间。那么，设置 pickup_to_delivery_relative_detour_limit 会强制执行以下条件：

start_time(delivery) - start_time(pickup) <=
std::ceil(t * (1.0 + pickup_to_delivery_relative_detour_limit))

如果同一批货件同时指定了相对限制和绝对限制，则对于每个可能的取货/送货对，系统会使用限制更严格的那个。截至 2017 年 10 月，只有在出行时长不取决于车辆时，系统才支持绕行。

加载

在执行访问时，如果访问是取货，则可能会在车辆负荷中添加预定义量；如果访问是送货，则可能会减去预定义量。此消息定义了相应金额。请参阅 load_demands。

字段
amount

int64

执行相应访问的车辆的负载量会有所不同。由于它是整数，因此建议用户选择合适的单位，以免损失精度。必须大于等于 0。

VisitRequest

车辆可完成的访问请求：具有地理位置（或两个，见下文）、以时间窗口表示的营业时间和结束时间，以及服务时长（车辆到达取货或送货地点后所花费的时间）。

字段
arrival_location

LatLng

执行此 VisitRequest 时车辆到达的地理位置。如果配送模型具有时长距离矩阵，则不得指定 arrival_location。
arrival_waypoint

Waypoint

执行此 VisitRequest 时车辆到达的途经点。如果配送模型具有时长距离矩阵，则不得指定 arrival_waypoint。
departure_location

LatLng

车辆在完成此 VisitRequest 后出发的地理位置。如果与 arrival_location 相同，则可以省略。如果配送模型具有时长距离矩阵，则不得指定 departure_location。
departure_waypoint

Waypoint

车辆在完成此 VisitRequest 后出发的途经点。如果与 arrival_waypoint 相同，则可以省略。如果配送模型具有时长距离矩阵，则不得指定 departure_waypoint。
tags[]

string

指定附加到访问请求的标记。不允许使用空字符串或重复的字符串。
time_windows[]

TimeWindow

限制访问到达时间的时间窗口。请注意，车辆可能会在到达时间窗口之外出发，也就是说，到达时间 + 时长不必在时间窗口内。如果车辆在 TimeWindow.start_time 之前到达，则可能会产生等待时间。

如果不存在 TimeWindow，则表示车辆可以在任意时间执行此访问。

时间窗口必须是不相交的，也就是说，任何时间窗口都不得与其他时间窗口重叠或相邻，并且必须按递增顺序排列。

只有当时间窗口为单个时，才能设置 cost_per_hour_after_soft_end_time 和 soft_end_time。
duration

Duration

访问时长，即车辆从到达到离开所花费的时间（将添加到可能的等待时间；请参阅 time_windows）。
cost

double

在车辆路线中服务此访问请求的费用。此属性可用于为货件的每种替代自提或送货方式支付不同的费用。此费用必须与 Shipment.penalty_cost 的单位相同，且不得为负值。
load_demands

map<string, Load>

相应访问请求的负载需求。这与 Shipment.load_demands 字段类似，只不过它仅适用于此 VisitRequest，而不是整个 Shipment。此处列出的需求会添加到 Shipment.load_demands 中列出的需求中。
visit_types[]

string

指定访问的类型。这可用于分配车辆完成此访问所需的额外时间（请参阅 Vehicle.extra_visit_duration_for_visit_type）。

一种类型只能出现一次。
label

string

为相应 VisitRequest 指定标签。此标签会在响应中以相应 ShipmentRoute.Visit 中的 visit_label 形式报告。
avoid_u_turns

bool

指定是否应避免在此位置的驾车路线中出现掉头。系统会尽力避免掉头，但无法保证完全避免。这是一项实验性功能，其行为可能会发生变化。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request。

ShipmentModel

配送模型包含一组必须由一组车辆执行的配送任务，同时尽可能减少总费用，即以下各项的总和：

  • 车辆的路线规划费用（所有车辆的总时间费用、行程时间费用和固定费用之和）。
  • 未履行的配送违规处置。
  • 全球货运时长的成本
字段
shipments[]

Shipment

必须在模型中执行的一组运输。
vehicles[]

Vehicle

可用于执行拜访的一组车辆。
objectives[]

Objective

此模型的要实现的目标集，我们将将其转换为费用。如果此参数不为空，则输入模型必须是无费用的。如需获取修改后的请求，请使用 solving_mode = TRANSFORM_AND_RETURN_REQUEST。请注意，在这种情况下，系统不会解决该请求。请参阅相关文档。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。
global_start_time

Timestamp

模型的全局开始时间和结束时间：此范围之外的时间均视为无效。

模型的跨度必须小于一年，即 global_end_time 和 global_start_time 之间的差值必须小于 31536000 秒。

使用 cost_per_*hour 字段时，您可能需要将此窗口设置为较小的时间间隔，以提高性能（例如，如果您对单日进行建模，则应将全局时间限制设置为该天）。如果未设置，则使用 1970 年 1 月 1 日 00:00:00 UTC（即秒数：0，纳秒数：0）作为默认值。
global_end_time

Timestamp

如果未设置，则使用 1971 年 1 月 1 日 00:00:00 UTC（即秒数：31536000，纳秒数：0）作为默认值。
global_duration_cost_per_hour

double

整个方案的“全局时长”是指所有车辆的最早有效开始时间与最晚有效结束时间之间的差值。用户可以为该量分配每小时费用，以尝试优化最早完成作业的时间。此费用的单位必须与 Shipment.penalty_cost 的单位相同。
duration_distance_matrices[]

DurationDistanceMatrix

指定模型中使用的时长和距离矩阵。如果此字段为空，系统会改用 Google 地图或测地线距离，具体取决于 use_geodesic_distances 字段的值。如果该值不为空，则 use_geodesic_distances 不能为 true，并且 duration_distance_matrix_src_tags 和 duration_distance_matrix_dst_tags 都不能为空。

用法示例：

  • 有两个位置：locA 和 locB。
  • 1 辆车从位置 A 开始其路线，并在位置 A 结束。
  • 在 locB 提交了 1 次取件预约请求。
model {
  vehicles { start_tags: "locA"  end_tags: "locA" }
  shipments { pickups { tags: "locB" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_dst_tags: "locA"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrices {
    rows {  # from: locA
      durations { seconds: 0 }   meters: 0    # to: locA
      durations { seconds: 100 } meters: 1000 # to: locB
    }
    rows {  # from: locB
      durations { seconds: 102 } meters: 990 # to: locA
      durations { seconds: 0 }   meters: 0   # to: locB
    }
  }
}
  • 有三个位置：locA、locB 和 locC。
  • 1 辆车从 locA 开始其路线，在 locB 结束，使用矩阵“fast”。
  • 1 辆车从 locB 开始其路线，并在 locB 结束，使用“慢”矩阵。
  • 1 辆车从 locB 开始其路线，在 locB 结束，使用矩阵“fast”。
  • 在 locC 提交了 1 次取件预约请求。
model {
  vehicles { start_tags: "locA" end_tags: "locB" start_tags: "fast" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "slow" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "fast" }
  shipments { pickups { tags: "locC" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_src_tags: "locC"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrix_dst_tags: "locC"
  duration_distance_matrices {
    vehicle_start_tag: "fast"
    rows {  # from: locA
      durations { seconds: 1000 } meters: 2000 # to: locB
      durations { seconds: 600 }  meters: 1000 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }   meters: 0    # to: locB
      durations { seconds: 700 } meters: 1200 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 702 } meters: 1190 # to: locB
      durations { seconds: 0 }   meters: 0    # to: locC
    }
  }
  duration_distance_matrices {
    vehicle_start_tag: "slow"
    rows {  # from: locA
      durations { seconds: 1800 } meters: 2001 # to: locB
      durations { seconds: 900 }  meters: 1002 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }    meters: 0    # to: locB
      durations { seconds: 1000 } meters: 1202 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 1001 } meters: 1195 # to: locB
      durations { seconds: 0 }    meters: 0    # to: locC
    }
  }
}
duration_distance_matrix_src_tags[]

string

用于定义时长矩阵和距离矩阵来源的标记；duration_distance_matrices(i).rows(j) 用于定义从具有标记 duration_distance_matrix_src_tags(j) 的访问到矩阵 i 中其他访问的时长和距离。

标记对应于 VisitRequest.tags 或 Vehicle.start_tags。给定的 VisitRequest 或 Vehicle 必须与此字段中的一个标记完全匹配。请注意，Vehicle 的来源、目的地和矩阵标记可能相同；同样，VisitRequest 的来源和目的地标记可能相同。所有标记必须各不相同，且不能是空字符串。如果此字段不为空，则 duration_distance_matrices 不得为空。
duration_distance_matrix_dst_tags[]

string

用于定义时长矩阵和距离矩阵的目的地的标记；duration_distance_matrices(i).rows(j).durations(k)（分别为 duration_distance_matrices(i).rows(j).meters(k))）用于定义从具有标记 duration_distance_matrix_src_tags(j) 的访问到具有标记 duration_distance_matrix_dst_tags(k) 的访问在矩阵 i 中的出行时长（分别为出行距离）。

标记对应于 VisitRequest.tags 或 Vehicle.start_tags。给定的 VisitRequest 或 Vehicle 必须与此字段中的一个标记完全匹配。请注意，Vehicle 的来源、目的地和矩阵标记可能相同；同样，VisitRequest 的来源和目的地标记可能相同。所有标记必须各不相同，且不能是空字符串。如果此字段不为空，则 duration_distance_matrices 不得为空。
transition_attributes[]

TransitionAttributes

向模型添加了过渡属性。
shipment_type_incompatibilities[]

ShipmentTypeIncompatibility

一组不兼容的 shipment_type（请参阅 ShipmentTypeIncompatibility）。
shipment_type_requirements[]

ShipmentTypeRequirement

一组 shipment_type 要求（请参阅 ShipmentTypeRequirement）。
precedence_rules[]

PrecedenceRule

必须在模型中强制执行的一组优先规则。

重要提示：使用优先级规则会限制可优化的问题的规模。如果请求使用包含大量货件的优先级规则，则可能会被拒绝。
max_active_vehicles

int32

限制活跃车辆的最大数量。如果车辆的路线至少执行一次配送，则该车辆处于活跃状态。如果驾驶员数量少于车辆数量，且车队由多种类型的车辆组成，则可以使用此限制来限制路线数量。然后，优化功能将选择要使用的最佳车辆子集。必须为严格正值。

DurationDistanceMatrix

指定从访问和车辆起始位置到访问和车辆结束位置的时长和距离矩阵。

字段
rows[]

Row

指定时长和距离矩阵的行。它必须具有与 ShipmentModel.duration_distance_matrix_src_tags 相同的元素数量。
vehicle_start_tag

string

用于定义相应时长和距离矩阵适用于哪些车辆的标记。如果为空，则表示适用于所有车辆，并且只能有一个矩阵。

每次车辆启动都必须与一个矩阵完全匹配，也就是说，车辆启动的 start_tags 字段必须与某个矩阵的 vehicle_start_tag 相匹配（并且只能与一个矩阵的 vehicle_start_tag 相匹配）。

所有矩阵都必须具有不同的 vehicle_start_tag。

行

指定时长和距离矩阵的某一行。

字段
durations[]

Duration

相应行的时长值。它必须具有与 ShipmentModel.duration_distance_matrix_dst_tags 相同的元素数量。
meters[]

double

相应行的距离值。如果模型中没有任何费用或限制条件涉及距离，则可将此参数留空；否则，此参数的元素数量必须与 durations 相同。

目标

目标完全取代了费用模型，因此与预先存在的费用不兼容。每个目标都对应于一些预定义的费用，例如车辆、货件或过渡属性的费用。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。

字段
type

Type

目标的类型。
weight

double

相应目标相对于其他目标的权重。可以是任何非负数，权重不必总和为 1。权重默认为 1.0。

类型

将映射到一组费用的目标类型。

枚举
DEFAULT 系统将使用一组默认费用，以确保获得合理的解决方案。注意：此目标可以单独使用，但如果用户指定的目标中不包含此目标，系统也会始终以 1.0 的权重将其作为基准添加到用户指定的目标中。
MIN_DISTANCE “MIN”目标。最大限度地缩短总行驶距离。
MIN_WORKING_TIME 最大限度地缩短所有车辆的总工作时间。
MIN_TRAVEL_TIME 与上述相同，但仅关注行程时间。
MIN_NUM_VEHICLES 尽可能减少所用车辆的数量。

PrecedenceRule

两个事件（每个事件都是货件的取件或送货）之间的优先规则：“第二个”事件必须在“第一个”事件开始后至少 offset_duration 开始。

多个优先关系可以指代同一（或相关）事件，例如“B 的取件发生在 A 的送达之后”和“C 的取件发生在 B 的取件之后”。

此外，只有在执行这两项运输服务时，优先级才适用，否则会被忽略。

字段
first_is_delivery

bool

表示“第一个”事件是否为送达事件。
second_is_delivery

bool

指明“第二个”事件是否为交付。
offset_duration

Duration

“第一个”事件和“第二个”事件之间的偏移量。可以是负值。
first_index

int32

“第一个”事件的货件索引。必须指定此字段。
second_index

int32

“第二个”事件的货件指数。必须指定此字段。

ShipmentRoute

车辆的路线可以沿时间轴分解，如下所示（假设有 n 次访问）：

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

请注意，我们区分了以下两种情况：

  • “准时事件”，例如车辆的开始和结束以及每次访问的开始和结束（也称为到达和离开）。它们发生在给定的秒数。
  • “时间间隔”，例如访问本身以及访问之间的过渡。虽然时间间隔有时可能持续时间为零（即开始和结束时间在同一秒），但通常具有正持续时间。

不变量：

  • 如果有 n 次访问，则有 n+1 次转化。
  • 访问始终位于之前的过渡（相同索引）和之后的过渡（索引 + 1）之间。
  • 车辆启动后，始终会执行过渡 #0。
  • 车辆结束时间始终位于过渡 #n 之前。

放大来看，在 Transition 和 Visit 期间会发生以下情况：

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

最后，以下是过渡期间 TRAVEL、BREAKS、DELAY 和 WAIT 的安排方式。

  • 它们不会重叠。
  • 延迟时间是唯一的，必须是下一次访问（或车辆结束）之前的连续时间段。因此，只需知道延迟时长，即可知道其开始时间和结束时间。
  • 中断是连续且不重叠的时间段。响应会指定每次中断的开始时间和时长。
  • TRAVEL 和 WAIT 是“可抢占”的：它们可以在此过渡期间多次中断。客户端可以假设 TRAVEL 会“尽快”发生，而“等待”会填补剩余时间。

一个（复杂）示例：

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
字段
vehicle_index

int32

执行路线的车辆，由其在来源 ShipmentModel 中的索引标识。
vehicle_label

string

执行此路线的车辆的标签，如果指定，则等于 ShipmentModel.vehicles(vehicle_index).label。
vehicle_start_time

Timestamp

车辆开始行驶路线的时间。
vehicle_end_time

Timestamp

车辆完成路线的时间。
visits[]

Visit

表示路线的有序访问序列。visits[i] 是路线中的第 i 次访问。如果此字段为空，则表示车辆未被使用。
transitions[]

Transition

相应路由的有序转换列表。
has_traffic_infeasibilities

bool

当 OptimizeToursRequest.consider_road_traffic 设置为 true 时，此字段表示系统会使用基于流量的出行时间估算值来预测路线时间的不一致性。在满足访问和车辆时间窗口的前提下，可能没有足够的时间来完成根据流量调整的行程、延迟以及访问之间、首次访问之前或最后一次访问之后的休息时间。例如，

  start_time(previous_visit) + duration(previous_visit) +
  travel_duration(previous_visit, next_visit) > start_time(next_visit)

由于交通状况导致出行时间估计值 travel_duration(previous_visit, next_visit) 增加，因此到达 next_visit 的时间可能会晚于当前时间窗口。此外，由于出行时间估计值增加以及访问或休息时间窗口限制，休息时间可能会被迫与访问时间重叠。
route_polyline

EncodedPolyline

路线的编码多段线表示法。只有当 OptimizeToursRequest.populate_polylines 设置为 true 时，系统才会填充此字段。
breaks[]

Break

执行此路线的车辆的预定休息时间。breaks 序列表示时间间隔，每个间隔从相应的 start_time 开始，持续 duration 秒。
metrics

AggregatedMetrics

相应路线的时长、距离和负载指标。AggregatedMetrics 的各个字段会根据具体情况在所有 ShipmentRoute.transitions 或 ShipmentRoute.visits 上求和。
vehicle_fullness

VehicleFullness

VehicleFullness 字段，用于计算受限指标与各自的车辆限值之间的接近程度。其字段是受限指标字段（例如 AggregatedMetrics.travel_distance_meters）与相关车辆限值（例如 Vehicle.route_distance_limit）之间的比率。

实验性：此字段的行为或存在状态将来可能会发生变化。
route_costs

map<string, double>

路线的费用，按与费用相关的请求字段细分。键是相对于输入 OptimizeToursRequest 的 proto 路径，例如“model.shipments.pickups.cost”，值是相应费用字段生成的总费用，汇总了整个路线的费用。换句话说，costs["model.shipments.pickups.cost"] 是路线中所有取货费用的总和。模型中定义的所有费用都会在此处详细报告，但与 TransitionAttributes 相关的费用除外，这些费用自 2022 年 1 月起仅以汇总方式报告。
route_total_cost

double

路线的总费用。费用地图中所有费用的总和。

休息时间

表示中断执行的数据。

字段
start_time

Timestamp

休息的开始时间。
duration

Duration

休息时长。

EncodedPolyline

多段线的编码表示法。如需详细了解多段线编码，请访问以下网址：https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding。

字段
points

string

表示多段线的编码点的字符串。

过渡

路线中两个事件之间的过渡。请参阅 ShipmentRoute 的说明。

如果车辆没有 start_location 和/或 end_location，则相应的出行指标为 0。

字段
travel_duration

Duration

此过渡期间的旅行时长。
travel_distance_meters

double

过渡期间的行驶距离。
traffic_info_unavailable

bool

当通过 OptimizeToursRequest.consider_road_traffic 请求路况信息，但无法检索到 Transition 的路况信息时，此布尔值会设置为 true。这可能是暂时性的（实时路况服务器出现罕见的小故障），也可能是永久性的（相应位置没有数据）。
delay_duration

Duration

应用于相应过渡的延迟时长的总和。如果有延迟，则延迟会在下一个事件（到访或车辆结束）开始前 delay_duration 秒开始。请参阅TransitionAttributes.delay。
break_duration

Duration

相应过渡期间发生的插播广告的时长总和（如果有）。有关每次插播广告的开始时间和时长的详细信息存储在 ShipmentRoute.breaks 中。
wait_duration

Duration

在此过渡期间的等待时间。等待时长对应于空闲时间，不包括休息时间。另请注意，此等待时间可能会分为多个不连续的时间段。
total_duration

Duration

过渡的总时长，为方便起见而提供。它等于：

  • 下一次访问 start_time（或 vehicle_end_time，如果这是最后一次过渡）- 相应过渡的 start_time；
  • 如果 ShipmentRoute.has_traffic_infeasibilities 为 false，则以下等式也成立：`total_duration = travel_duration + delay_duration
  • break_duration + wait_duration”。
start_time

Timestamp

相应过渡的开始时间。
route_polyline

EncodedPolyline

过渡期间所遵循路线的编码多段线表示法。只有当 populate_transition_polylines 设置为 true 时，系统才会填充此字段。
route_token

string

仅限输出。一个不透明的令牌，可传递给 Navigation SDK，以便在导航期间重建路线，并在重新规划路线时遵循创建路线时的原始意图。将此令牌视为不透明 blob。请勿跨请求比较其值，因为即使服务返回完全相同的路线，其值也可能会发生变化。只有当 populate_transition_polylines 设置为 true 时，系统才会填充此字段。
vehicle_loads

map<string, VehicleLoad>

相应车辆在过渡期间的载重，针对的是该车辆的 Vehicle.load_limits 中显示的每种类型，或者在该路线上执行的某些运输中具有非零 Shipment.load_demands 的每种类型。

第一次过渡期间的载荷是车辆路线的起始载荷。然后，在每次访问之后，系统会根据访问是取货还是送货，将访问的 load_demands 添加到起始载荷中或从起始载荷中减去，以获得下一次过渡的载荷。

VehicleLoad

报告车辆在路线上的某个时间点的实际载重，适用于指定类型（请参阅 Transition.vehicle_loads）。

字段
amount

int64

车辆上给定类型的负荷量。负载的单位通常由类型指示。请参阅 Transition.vehicle_loads。

访问

在路线期间进行的拜访。此访问记录对应于 Shipment 的取件或送件。

字段
shipment_index

int32

来源 ShipmentModel 中 shipments 字段的索引。
is_pickup

bool

如果为 true，则表示相应访问是取货访问。否则，表示相应访问是送货访问。Shipment。
visit_request_index

int32

Shipment 的自取或送货字段中 VisitRequest 的索引（请参阅 is_pickup）。
start_time

Timestamp

访问的开始时间。请注意，车辆可能会比此时间更早到达访问地点。时间与 ShipmentModel 保持一致。
load_demands

map<string, Load>

总访问负载需求，即货件和访问请求 load_demands 的总和。如果访问是送货，则值为负。需求量与 Transition.loads 的类型相同（请参阅此字段）。
detour

Duration

由于在到访之前访问了路线上的其他配送点，以及时间窗口可能造成的等待时间，而产生的额外绕行时间。如果到访是送货，则绕行时间是从相应的取货到访计算得出的，等于：

start_time(delivery) - start_time(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

否则，该值将根据车辆 start_location 计算得出，等于：

start_time - vehicle_start_time - travel duration from
the vehicle's `start_location` to the visit.
shipment_label

string

相应 Shipment.label 的副本（如果已在 Shipment 中指定）。
visit_label

string

相应 VisitRequest.label 的副本（如果已在 VisitRequest 中指定）。
visit_type

VisitType

可选。指定访问类型。替换 Visit.is_pickup 字段。
injected_solution_location_token

int32

一个不透明的令牌，表示有关访问位置的信息。

如果相应访问的 VisitRequest.avoid_u_turns 设置为 true，或者如果请求 OptimizeToursRequest 中的 ShipmentModel.avoid_u_turns 设置为 true，则此字段可能会在结果路线的访问中填充。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request。

VisitType

表示相应访问是自提、送货上门还是前往 Stop 的访问。只有在启用多模态优化时，系统才会使用前往 Stop 的访问。

枚举
VISIT_TYPE_UNSPECIFIED 未指定访问类型。
PICKUP_SHIPMENT 访问对应于取件。
DELIVER_SHIPMENT 访问对应于送货。

ShipmentTypeIncompatibility

指定了不同货件类型之间的不兼容性。系统会根据不兼容模式限制同一路线中不兼容货件的显示。

字段
types[]

string

不兼容的类型列表。如果两批货件的shipment_types不同，则它们“不兼容”。
incompatibility_mode

IncompatibilityMode

应用于不兼容情况的模式。

IncompatibilityMode

用于定义如何限制同一路线上的不兼容货件的外观的模式。

枚举
INCOMPATIBILITY_MODE_UNSPECIFIED 未指定不兼容模式。不应使用此值。
NOT_PERFORMED_BY_SAME_VEHICLE 在此模式下，类型不兼容的两批货物永远无法共用同一辆车。
NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY

在此模式下，两种不兼容的货物绝不能同时装在同一辆车上：

  • 只有在其中一辆车送达后，另一辆车才能被取走，否则无法共用同一辆车。
  • 如果两批货件都只能自取（不能配送）或只能配送（不能自取），则它们根本无法共用同一辆车。

ShipmentTypeRequirement

根据货件的 shipment_type 指定货件之间的要求。要求的具体情况由要求模式定义。

字段
required_shipment_type_alternatives[]

string

dependent_shipment_types 所需的备选配送类型列表。
dependent_shipment_types[]

string

如果配送的类型在 dependent_shipment_types 字段中，则必须在同一路线中至少访问一次类型为 required_shipment_type_alternatives 的配送。

注意：不允许出现 shipment_type 依赖于自身的依赖链。
requirement_mode

RequirementMode

应用于要求的模式。

RequirementMode

用于定义路线上的相关货件外观的模式。

枚举
REQUIREMENT_MODE_UNSPECIFIED 未指定要求模式。不应使用此值。
PERFORMED_BY_SAME_VEHICLE 在此模式下，所有“相关”货件都必须与至少一个“必需”货件共用同一辆车。
IN_SAME_VEHICLE_AT_PICKUP_TIME

在 IN_SAME_VEHICLE_AT_PICKUP_TIME 模式下，所有“相关”货件在取件时，其车辆上都必须至少有一个“必需”货件。

因此，“相关”取件必须具有以下任一特征：

  • 仅限送货的“必需”配送在路线上的送达时间晚于或
  • 在路线中先于“必需”货件取件，并且如果“必需”货件有送货，则必须在“相关”货件取件后执行此送货。
IN_SAME_VEHICLE_AT_DELIVERY_TIME 与之前相同，只是“相关”货件在配送时需要有“必需”货件在车上。

SkippedShipment

指定解决方案中未执行的配送的详细信息。对于微不足道的情况和/或如果我们能够确定跳过的原因，我们会在此处报告原因。

字段
index

int32

该指数对应于来源 ShipmentModel 中相应配送的指数。
label

string

相应 Shipment.label 的副本（如果已在 Shipment 中指定）。
reasons[]

Reason

说明跳过相应配送的原因的列表。请参阅上方的注释 Reason。如果我们无法理解跳过相应配送的原因，则不会设置原因。
penalty_cost

double

这是 Shipment.penalty_cost 的副本，此处包含该副本是为了方便您了解跳过配送的严重程度。

实验性：此字段的行为或存在状态将来可能会发生变化。
estimated_incompatible_vehicle_ratio

double

因以下至少一个原因而无法执行相应配送任务的车辆的估计比率。注意：只有当原因涉及车辆时，才会填充此字段。

实验性：此字段的行为或存在状态将来可能会发生变化。

原因

如果我们能说明为什么跳过相应配送，原因会列在此处。如果所有车辆的原因不尽相同，reason 将包含多个元素。跳过的配送不能有重复原因，即除了 example_vehicle_index 之外的所有字段都相同。示例：

reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 1
  example_exceeded_capacity_type: "Apples"
}
reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 3
  example_exceeded_capacity_type: "Pears"
}
reasons {
  code: CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT
  example_vehicle_index: 1
}

跳过的配送与所有车辆都不兼容。每辆车超出容量或距离限制的原因可能各不相同，但至少有一辆车的“苹果”容量会超出（包括车辆 1），至少有一辆车的“梨”容量会超出（包括车辆 3），并且至少有一辆车的距离限制会超出（包括车辆 1）。

字段
code

Code

请参阅代码的注释。
example_vehicle_indices[]

int32

与 example_vehicle_index 相同，只不过我们提供的是多个已识别车辆的列表。此列表未必详尽无遗。仅当 [fill_example_vehicle_indices_in_skipped_reasons][] 为 true 时，才会填充此字段。

实验性：此字段的行为或存在状态将来可能会发生变化。
example_exceeded_capacity_type

string

如果原因代码为 DEMAND_EXCEEDS_VEHICLE_CAPACITY，则表示文档超出了一种容量类型。
example_vehicle_index

int32

如果原因是与货件-车辆不兼容相关，则此字段会提供相关车辆的索引。

代码

用于标识原因类型的代码。这里的顺序无关紧要。特别是，它不会指示在解决方案中，如果两个原因都适用，哪个原因会出现在另一个原因之前。

枚举
CODE_UNSPECIFIED 不应使用此值。
NO_VEHICLE 模型中没有车辆导致所有配送都不可行。
DEMAND_EXCEEDS_VEHICLE_CAPACITY 货件的需求超过了车辆的某些容量类型（包括 example_exceeded_capacity_type）的容量。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT

执行此配送任务所需的最短距离（即从车辆的 start_location 到配送任务的上车地点和/或送货地点以及车辆的最终地点）超过了车辆的 route_distance_limit。

请注意，在此计算中，我们使用的是测地线距离。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT

执行此配送任务所需的最短时间（包括行程时间、等待时间和服务时间）超过了车辆的 route_duration_limit。

注意：行程时间是在最佳情况下计算的，即测地线距离 x 36 米/秒（大约 130 公里/小时）。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TRAVEL_DURATION_LIMIT 与上例相同，但我们只比较最短行程时间和车辆的 travel_duration_limit。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TIME_WINDOWS 如果车辆在最早的开始时间开始配送，则在最佳情况下（有关时间计算，请参阅 CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT），车辆也无法完成此配送任务：总时间会导致车辆在最晚的结束时间之后结束配送。
VEHICLE_NOT_ALLOWED 相应货件的 allowed_vehicle_indices 字段不为空，但相应车辆不属于该货件。
VEHICLE_IGNORED

车辆的 ignore 字段为 true。

实验性：此字段的行为或存在状态将来可能会发生变化。
SHIPMENT_IGNORED

相应货件的 ignore 字段为 true。

实验性：此字段的行为或存在状态将来可能会发生变化。
SKIPPED_IN_INJECTED_SOLUTION_CONSTRAINT

在 injected_solution_constraint 中跳过了相应配送。

实验性：此字段的行为或存在状态将来可能会发生变化。
VEHICLE_ROUTE_IS_FULLY_SEQUENCE_CONSTRAINED

injected_solution_constraint 中指定的车辆路线放宽条件不允许插入任何访问。

实验性：此字段的行为或存在状态将来可能会发生变化。
ZERO_PENALTY_COST

相应货件的违规罚款为零。虽然这可以作为一种高级建模选择，但事后也可能解释了为什么跳过某次配送。

实验性：此字段的行为或存在状态将来可能会发生变化。

TimeWindow

时间窗口用于限制事件的时间，例如访问的到达时间或车辆的开始时间和结束时间。

硬时间范围界限 start_time 和 end_time 用于强制执行事件的最早时间和最晚时间，因此 start_time <= event_time <= end_time。软时间范围下限 soft_start_time 表示希望事件发生在 soft_start_time 或之后，但会产生与事件发生在 soft_start_time 之前的时间成正比的费用。软时间范围上限 soft_end_time 表示希望事件发生在 soft_end_time 或之前，但会产生与事件发生在 soft_end_time 之后的时间成正比的费用。start_time、end_time、soft_start_time 和 soft_end_time 应在全局时间限制（请参阅 ShipmentModel.global_start_time 和 ShipmentModel.global_end_time）内，并且应遵循以下规则：

  0 <= `start_time` <= `end_time` and
  0 <= `start_time` <= `soft_start_time` and
  0 <= `soft_end_time` <= `end_time`.
字段
start_time

Timestamp

硬性时间窗口开始时间。如果未指定，则设置为 ShipmentModel.global_start_time。
end_time

Timestamp

硬性时间窗口结束时间。如果未指定，则会设置为 ShipmentModel.global_end_time。
soft_start_time

Timestamp

时间窗口的软开始时间。
soft_end_time

Timestamp

时间段的软结束时间。
cost_per_hour_before_soft_start_time

double

如果相应事件发生在 soft_start_time 之前，则添加到模型中其他费用的每小时费用，计算方式如下：

   max(0, soft_start_time - t.seconds)
                          * cost_per_hour_before_soft_start_time / 3600,
t being the time of the event.

此费用必须为正值，并且只有在设置了 soft_start_time 的情况下才能设置此字段。
cost_per_hour_after_soft_end_time

double

如果事件发生在 soft_end_time 之后，则添加到模型中其他费用的每小时费用，计算方式如下：

   max(0, t.seconds - soft_end_time.seconds)
                    * cost_per_hour_after_soft_end_time / 3600,
t being the time of the event.

此费用必须为正数，并且只有在已设置 soft_end_time 的情况下才能设置此字段。

TransitionAttributes

指定路线中两次连续访问之间过渡的属性。多个 TransitionAttributes 可能适用于同一过渡：在这种情况下，所有额外费用都会累加，并应用最严格的限制（遵循自然的“AND”语义）。

字段
src_tag

string

用于定义这些属性所适用的 (src->dst) 过渡的标记。

当来源访问或车辆启动的 VisitRequest.tags 或 Vehicle.start_tags 包含 src_tag 或不包含 excluded_src_tag 时（具体取决于这两个字段中哪个不为空），即表示匹配。
excluded_src_tag

string

请参阅 src_tag。src_tag 和 excluded_src_tag 中必须只有一个不为空。
dst_tag

string

当目的地访问或车辆行程结束的 VisitRequest.tags 或 Vehicle.end_tags 包含 dst_tag 或不包含 excluded_dst_tag 时（具体取决于这两个字段中哪个不为空），才算匹配。
excluded_dst_tag

string

请参阅 dst_tag。dst_tag 和 excluded_dst_tag 中必须只有一个不为空。
cost

double

指定执行此过渡的费用。此费用与模型中的所有其他费用采用相同的单位，且不得为负值。它会添加到所有其他现有费用之上。
cost_per_kilometer

double

指定在执行此过渡时，按行驶距离计算的每公里费用。它会累加车辆上指定的所有 Vehicle.cost_per_kilometer。
distance_limit

DistanceLimit

指定在执行此过渡时行驶的距离限制。

截至 2021 年 6 月，仅支持软限制。
delay

Duration

指定执行此过渡时产生的延迟。

此延迟始终发生在完成来源访问之后和开始目标访问之前。

URI

指向可由 Route Optimization API 读取和写入的资源的通用资源标识符。

字段
uri

string

资源的 URI。资源可能尚不存在。

资源的内容编码为 JSON 或 textproto。仅支持 Google Cloud Storage 资源。如果资源以 JSON 格式编码，则资源名称必须以 .json 为后缀。如果资源以 textproto 格式编码，则资源名称必须以 .txtpb 为后缀。例如，JSON 编码文件的 Google Cloud Storage URI 可能如下所示：gs://bucket/path/input/object.json。

交通工具

用于表示运送问题中的车辆。解决配送问题将为相应车辆构建一条从 start_location 开始到 end_location 结束的路线。路线是一系列访问（请参阅 ShipmentRoute）。

字段
display_name

string

车辆的用户自定义显示名称。不得超过 63 个字符，可以使用 UTF-8 字符。
travel_mode

TravelMode

出行模式，会影响车辆可行驶的道路及其行驶速度。另请参阅 travel_duration_multiple。
route_modifiers

RouteModifiers

一组需要满足的条件，这些条件会影响指定车辆的路线计算方式。
start_location

LatLng

车辆在取货前开始行驶的地理位置。如果未指定，车辆将从第一个上车点开始。如果配送模型具有时长和距离矩阵，则不得指定 start_location。
start_waypoint

Waypoint

表示车辆在取货前开始行驶的地理位置的途经点。如果未指定 start_waypoint 和 start_location，车辆将从第一个上车点开始。如果配送模型具有时长和距离矩阵，则不得指定 start_waypoint。
end_location

LatLng

车辆完成最后一次 VisitRequest 后停止的地理位置。如果未指定，车辆的 ShipmentRoute 会在完成最后一次 VisitRequest 后立即结束。如果配送模型具有时长和距离矩阵，则不得指定 end_location。
end_waypoint

Waypoint

表示车辆在完成最后一次 VisitRequest 后结束的地理位置的途经点。如果未指定 end_waypoint 和 end_location，则车辆在完成最后一次 VisitRequest 后立即结束 ShipmentRoute。如果配送模型具有时长和距离矩阵，则不得指定 end_waypoint。
start_tags[]

string

指定附加到车辆路线起点的标记。

不允许使用空字符串或重复的字符串。
end_tags[]

string

指定附加到车辆路线末尾的标记。

不允许使用空字符串或重复的字符串。
start_time_windows[]

TimeWindow

车辆可以离开其起始位置的时间窗口。这些时间窗口必须在全局时间限制内（请参阅 ShipmentModel.global_* 字段）。如果未指定，则除了全局时间限制之外，没有其他限制。

属于同一重复字段的时间窗口必须是不相交的，即任何时间窗口都不能与另一个时间窗口重叠或相邻，并且它们必须按时间顺序排列。

只有当时间窗口为单个时，才能设置 cost_per_hour_after_soft_end_time 和 soft_end_time。
end_time_windows[]

TimeWindow

车辆可能到达最终位置的时间窗口。这些时间窗口必须在全局时间限制内（请参阅 ShipmentModel.global_* 字段）。如果未指定，则除了全局时间限制之外，没有其他限制。

属于同一重复字段的时间窗口必须是不相交的，即任何时间窗口都不能与另一个时间窗口重叠或相邻，并且它们必须按时间顺序排列。

只有当时间窗口为单个时，才能设置 cost_per_hour_after_soft_end_time 和 soft_end_time。
unloading_policy

UnloadingPolicy

在车辆上强制执行的卸货政策。
load_limits

map<string, LoadLimit>

车辆的载重能力（例如重量、体积、托盘数量）。映射中的键是负载类型的标识符，与 Shipment.load_demands 字段的键一致。如果此映射中缺少某个给定的键，则相应容量被视为无限。
cost_per_hour

double

车辆费用：所有费用加起来必须与 Shipment.penalty_cost 的单位相同。

车辆路线的每小时费用。此费用适用于路线的总耗时，包括行程时间、等待时间和游览时间。使用 cost_per_hour 而不是仅使用 cost_per_traveled_hour 可能会导致额外的延迟时间。
cost_per_traveled_hour

double

车辆路线每行驶小时的费用。此费用仅适用于路线所用的行程时间（即 ShipmentRoute.transitions 中报告的时间），不包括等待时间和拜访时间。
cost_per_kilometer

double

车辆路线的每公里费用。此费用适用于 ShipmentRoute.transitions 中报告的距离，不适用于从单个 VisitRequest 的 arrival_location 到 departure_location 隐式行驶的任何距离。
fixed_cost

double

如果使用相应车辆处理货件，则应用固定费用。
used_if_route_is_empty

bool

此字段仅适用于路线不服务于任何货件的车辆。它用于指明在这种情况下是否应将车辆视为已使用。

如果为 true，车辆会从起始位置前往结束位置，即使它不运送任何货物，并且系统会考虑从起始位置到结束位置的行驶所产生的时间和距离成本。

否则，车辆不会从起点行驶到终点，并且不会为该车辆安排 break_rule 或延迟（从 TransitionAttributes 开始）。在这种情况下，车辆的 ShipmentRoute 不包含任何信息，仅包含车辆索引和标签。
route_duration_limit

DurationLimit

适用于车辆路线总时长的限制。在给定的 OptimizeToursResponse 中，车辆的路线时长是其 vehicle_end_time 与 vehicle_start_time 之间的差值。
travel_duration_limit

DurationLimit

应用于车辆路线的行驶时长的限制。在给定的 OptimizeToursResponse 内，路线行驶时长是其所有 transitions.travel_duration 的总和。
route_distance_limit

DistanceLimit

应用于车辆路线总距离的限制。在给定的 OptimizeToursResponse 内，路线距离是所有 transitions.travel_distance_meters 的总和。
extra_visit_duration_for_visit_type

map<string, Duration>

指定从 visit_types 字符串到时长的映射。时长是指在具有指定 visit_types 的访问中，除了 VisitRequest.duration 之外还要花费的时间。如果指定了 cost_per_hour，则此额外访问时长会增加费用。键（即 visit_types）不能是空字符串。

如果访问请求具有多种类型，则系统会为地图中的每种类型添加时长。
break_rule

BreakRule

描述要在此车辆上强制执行的休息时间表。如果为空，则不会为相应车辆安排休息时间。
label

string

指定相应车辆的标签。此标签会在响应中报告为相应 ShipmentRoute 的 vehicle_label。
ignore

bool

如果为 true，则 used_if_route_is_empty 必须为 false，并且相应车辆将保持未使用状态。

如果某项配送任务由 injected_first_solution_routes 中被忽略的车辆执行，则该任务会在第一个解决方案中被跳过，但可以在响应中自由执行。

如果某项配送由 injected_solution_constraint 中被忽略的车辆执行，并且任何相关的取货/送货操作都受限于只能由该车辆执行（即，未放宽到 RELAX_ALL_AFTER_THRESHOLD 级别），则该配送会在响应中被跳过。如果某项配送的 allowed_vehicle_indices 字段不为空，但所有允许的车辆都被忽略，则该配送会在响应中被跳过。
travel_duration_multiple

double

指定可用于增加或减少相应车辆的出行时间的乘数。例如，如果将此值设置为 2.0，则表示相应车辆速度较慢，行程时间是标准车辆的两倍。此倍数不会影响访问时长。如果指定了 cost_per_hour 或 cost_per_traveled_hour，则会影响费用。此值必须在 [0.001, 1000.0] 范围内。如果未设置，则表示车辆为标准车辆，相应倍数视为 1.0。

警告：在应用此倍数后但在执行任何数值运算之前，系统会将出行时间四舍五入到最接近的秒数，因此较小的倍数可能会导致精度损失。

另请参阅下文中的 extra_visit_duration_for_visit_type。

DurationLimit

用于定义车辆路线的最长时长的限制。可以是硬性或软性。

定义软限制字段时，必须同时定义软上限阈值及其关联的费用。

字段
max_duration

Duration

将时长限制为最多 max_duration 的硬性限制。
soft_max_duration

Duration

一种不强制执行最长时长限制的软限制，但如果违反此限制，路线会产生费用。此费用会与其他在模型中定义的费用相加，单位相同。

如果定义了 soft_max_duration，则该值必须为非负数。如果还定义了 max_duration，则 soft_max_duration 必须小于 max_duration。
quadratic_soft_max_duration

Duration

一种软性限制，不会强制执行最长时长限制，但如果违反此限制，路线的费用将按时长的二次方计算。此费用会与模型中定义的其他费用相加，单位相同。

如果设置了 quadratic_soft_max_duration，则必须满足以下条件：

  • 必须为非负数。
  • 必须定义 max_duration。
  • quadratic_soft_max_duration 必须小于 max_duration。
  • 差值不得超过一天：max_duration - quadratic_soft_max_duration <= 86400 seconds
cost_per_hour_after_soft_max

double

如果违反 soft_max_duration 阈值，则每小时产生的费用。如果时长低于阈值，则额外费用为 0；否则，费用取决于时长，如下所示：

  cost_per_hour_after_soft_max * (duration - soft_max_duration)

费用必须为非负值。
cost_per_square_hour_after_quadratic_soft_max

double

如果违反 quadratic_soft_max_duration 阈值，则产生的每平方小时费用。

如果时长低于阈值，则额外费用为 0；否则，费用取决于时长，如下所示：

  cost_per_square_hour_after_quadratic_soft_max *
  (duration - quadratic_soft_max_duration)^2

费用必须为非负值。

LoadLimit

定义适用于车辆的载重限制，例如“此卡车最多只能载重 3, 500 公斤”。请参阅 load_limits。

字段
soft_max_load

int64

负载的软性限制。请参阅 cost_per_unit_above_soft_max。
cost_per_unit_above_soft_max

double

如果车辆在行驶路线上的载重超过 soft_max_load，则会产生以下费用惩罚（每辆车仅一次）：（载重 - soft_max_load）* cost_per_unit_above_soft_max。所有费用加起来必须与 Shipment.penalty_cost 的单位相同。软限制只能针对在整个模型中仅适用于取货或仅适用于送货的类型进行定义。
start_load_interval

Interval

车辆在路线开始时的可接受载荷区间。
end_load_interval

Interval

路线结束时车辆的可接受载荷区间。
max_load

int64

可接受的最大负载量。
cost_per_kilometer

LoadCost

此车辆每移动一个单位的负荷一公里所需的费用。此值可用作燃油消耗量的代理变量：如果负荷是重量（以牛顿为单位），则负荷*公里具有能量的维度。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。
cost_per_traveled_hour

LoadCost

此车辆在 1 小时内运输一个单位的负载所需的费用。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。

间隔

可接受的负载量区间。

字段
min

int64

最低可接受的负载。必须 ≥ 0。如果同时指定了这两个值，则 min 必须 ≤ max。
max

int64

可接受的最大负载。必须 ≥ 0。如果未指定，则此消息不会限制最大负载。如果同时指定了这两个值，则 min 必须 ≤ max。

LoadCost

在 Transition 期间移动一个单位的负载的费用。对于给定的负载，费用由两部分组成：

  • min(load, load_threshold) * cost_per_unit_below_threshold
  • max(0, load - load_threshold) * cost_per_unit_above_threshold

在这种费用下，解决方案会优先满足高需求，或者等效地最后满足高需求。例如，如果车辆有

load_limit {
  key: "weight"
  value {
    cost_per_kilometer {
      load_threshold: 15
      cost_per_unit_below_threshold: 2.0
      cost_per_unit_above_threshold: 10.0
    }
  }
}

其路线为：起点、上车点、上车点、送达点、送达点、终点，并包含以下过渡：

transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 20 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }

那么，此 LoadCost 产生的费用为（低于成本 * 低于的负荷 * 公里数 + 高于成本 * 高于的负荷 * 公里数）

  • 过渡 0：0.0
  • 过渡 1：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 过渡 2：2.0 * 15 * 1.0 + 10.0 * (20 - 15) * 1.0 = 80.0
  • 过渡 3：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 过渡 4：0.0

因此，该路线上的 LoadCost 为 120.0。

不过，如果路线是“起点、取货点、送货点、取货点、送货点、终点”，且包含以下过渡：

transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }

那么此 LoadCost 产生的费用为

  • 过渡 0：0.0
  • 过渡 1：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 过渡 2：0.0
  • 过渡 3：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 过渡 4：0.0

这里，路线的 LoadCost 为 40.0。

LoadCost 使得具有繁重过渡的解决方案更加昂贵。

实验性功能：如需了解详情，请参阅 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。

字段
load_threshold

int64

负载量，当负载量高于此值时，移动单位负载的费用将从 cost_per_unit_below_threshold 变为 cost_per_unit_above_threshold。必须 >= 0。
cost_per_unit_below_threshold

double

移动一个单位的负载的费用，适用于 0 到阈值之间的每个单位。必须是有限值，且大于等于 0。
cost_per_unit_above_threshold

double

移动一个单位的负载（对于超出阈值的每个单位）的费用。如果阈值为 0，则表示每单位固定费用。必须是有限值，且大于等于 0。

TravelMode

车辆可使用的出行方式。

这些应是 Google Maps Platform Routes API 出行模式的子集，请参阅：https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteTravelMode

注意：WALKING 路线目前处于 Beta 版阶段，有时可能没有清晰的人行道或步道。您必须向用户显示此警告，以告知用户您在应用中显示的所有步行路线。

枚举
TRAVEL_MODE_UNSPECIFIED 未指定的出行方式，相当于 DRIVING。
DRIVING 与行车路线（汽车、...）对应的出行模式。
WALKING 与步行路线对应的出行方式。

UnloadingPolicy

有关如何卸载车辆的政策。仅适用于同时包含取货和送货的货件。

其他货件可免费在路线上的任何位置发生，不受 unloading_policy 的限制。

枚举
UNLOADING_POLICY_UNSPECIFIED 未指定卸货政策；送货必须在相应的取货之后进行。
LAST_IN_FIRST_OUT 送货必须按取货的相反顺序进行
FIRST_IN_FIRST_OUT 送货顺序必须与取货顺序相同

VehicleFullness

VehicleFullness 是一种用于计算车辆满载程度的指标。每个 VehicleFullness 字段的值都介于 0 和 1 之间，计算方式为有上限的指标字段（例如 AggregatedMetrics.travel_distance_meters）与其相关车辆限值（例如 Vehicle.route_distance_limit）的比率（如果存在）。否则，饱腹感比率将保持未设置状态。如果限制为 0，则该字段设置为 1。注意：如果路线存在流量不可行性，某些原始满载率可能会超过 1.0，例如，车辆可能会超出其距离限制。在这些情况下，我们会将饱腹度值上限设为 1.0。

字段
max_fullness

double

相应消息中所有其他字段的最大值。
distance

double

AggregatedMetrics.travel_distance_meters 与 Vehicle.route_distance_limit 之间的比率。如果未设置 Vehicle.route_distance_limit，则此字段也将未设置。
travel_duration

double

[AggregatedMetrics.travel_duration_seconds][] 与 Vehicle.travel_duration_limit 之间的比率。如果未设置 Vehicle.travel_duration_limit，则此字段也将处于未设置状态。
active_duration

double

[AggregatedMetrics.total_duration_seconds][] 与 Vehicle.route_duration_limit 之间的比率。如果未设置 Vehicle.route_duration_limit，则此字段也将未设置。
max_load

double

所有类型的 [AggregatedMetrics.max_load][] 及其各自的 Vehicle.load_limits 之间的最大比率。如果所有 Vehicle.load_limits 字段均未设置，则此字段将未设置。
active_span

double

给定车辆的（vehicle_end_time - vehicle_start_time）/（latest_vehicle_end_time - earliest_vehicle_start_time）比率。如果分母不存在，则改用（ShipmentModel.global_end_time - ShipmentModel.global_start_time）。

航点

封装了途经点。途经点用于标记 VisitRequest 的到达和出发地点，以及车辆的起始和结束地点。

字段
side_of_road

bool

可选。表示此途经点的位置旨在让车辆优先停靠在道路的特定一侧。设置此值后，路线将经过相应位置，以便车辆停靠在道路中心偏向该位置的一侧。此选项不适用于“步行”出行模式。
vehicle_stopover

bool

表示该航点是供车辆停靠的地点，目的是接载或送达乘客。此选项仅适用于“DRIVING”出行模式，且“location_type”为“location”。

实验性：此字段的行为或存在状态将来可能会发生变化。
联合字段 location_type。表示位置的不同方式。location_type 只能是下列其中一项：
location

Location

使用地理坐标指定的点，包括可选的航向。
place_id

string

与途经点关联的 POI 地点 ID。

使用地点 ID 指定 VisitRequest 的到达或出发地点时，请使用足够具体的地点 ID，以便确定前往该地点的导航 LatLng 位置。例如，表示建筑物的地点 ID 是合适的，但不建议使用表示道路的地点 ID。