ShipmentModel

string

用户定义的运单显示名称。长度不得超过 63 个字符，且可以使用 UTF-8 字符。

object (VisitRequest)

与运单关联的一组备选自提选项。如果未指定，车辆只需前往与送货相对应的地点。

object (VisitRequest)

与运单关联的一组备选配送方式。如果未指定，车辆只需前往与上车点相对应的位置。

map (key: string, value: object (Load))

加载货物需求信息（例如重量、体积、托盘数量等）。映射中的键应该是描述相应加载类型的标识符，最好也包括单位。例如：“weight_kg”“volume_gallons”“pallet_count”等。如果给定键未出现在映射中，则相应的加载会被视为 null。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

integer

可以履行此运单的一组车辆。如果留空，所有车辆都可以执行此操作。车辆由其在 ShipmentModel 的 vehicles 列表中的索引指定。

number

指定每辆车交付此运单时产生的费用。如果指定，它必须具有以下 EITHER：

• 元素数量与 costsPerVehicleIndices 相同。costsPerVehicle[i] 对应于模型的车辆 costsPerVehicleIndices[i]。
• 元素数量与模型中车辆数量相同。第 i-th 元素对应于模型的第 #i 辆车。

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

integer

costsPerVehicle 所适用的车辆的索引。如果非空，则其元素数量必须与 costsPerVehicle 相同。一个车辆索引只能指定一次。如果某个车辆已从 costsPerVehicleIndices 中排除，则其费用为零。

string (Duration format)

指定与从自提到送餐的最短路径相比的最长绝对绕行时间。如果指定，则必须为非负数，并且运单中必须至少包含自提和送货信息。

例如，可以是从所选的自提备选方案直接到所选的备选配送方式所需的最短时间。然后，设置 pickupToDeliveryAbsoluteDetourLimit 会强制执行：

startTime(delivery) - startTime(pickup) <=
t + pickupToDeliveryAbsoluteDetourLimit

如果为同一批商品同时指定了相对限制和绝对限制，系统会对每个可能的自提/送货对使用更具限制性的限制。从 2017 年 10 月 10 日开始，仅当行程时长不取决于车辆时才支持绕行。

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

string (Duration format)

指定从开始自提到开始配送的最长时长。如果指定，则必须为非负数，并且运单中必须至少包含自提和送货信息。这既不取决于为自提和配送选择的替代选项，也不取决于车辆速度。这可以与最大绕行约束条件一起指定：解决方案将同时遵循这两种规范。

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

string

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

与为单次访问指定的 visitTypes 不同：属于同一运单的所有自取/配送都共用同一个 shipmentType。

string

指定此运单的标签。此标签会在相应 ShipmentRoute.Visit 的 shipmentLabel 的响应中报告。

boolean

如果为 true，则跳过此运单，但不应用 penaltyCost。

如果模型中存在任何 shipmentTypeRequirements，忽略运单会导致验证错误。

允许忽略在 injectedFirstSolutionRoutes 或 injectedSolutionConstraint 中执行的配送；求解器会从执行路线中移除相关的自提/送货访问信息。引用已忽略的运单的precedenceRules也会被忽略。

number

如果未能完成运输，则此处罚将添加到路线的总费用中。如果使用了某个自提和配送备选方式，则视为配送已完成。费用可以用用于模型中所有其他费用相关字段的相同单位表示，并且必须为正值。

重要提示：如果未指定此处罚，则会被视为无限期，即必须完成发货。

number

指定与从自提到送餐的最短路径相比的最长相对绕行时间。如果指定，则必须为非负数，并且运单中必须至少包含自提和送货信息。

例如，可以是从所选的自提备选方案直接到所选的备选配送方式所需的最短时间。然后，设置 pickupToDeliveryRelativeDetourLimit 会强制执行：

startTime(delivery) - startTime(pickup) <=
std::ceil(t * (1.0 + pickupToDeliveryRelativeDetourLimit))

如果为同一批商品同时指定了相对限制和绝对限制，系统会对每个可能的自提/送货对使用更具限制性的限制。从 2017 年 10 月 10 日开始，仅当行程时长不取决于车辆时才支持绕行。

object (LatLng)

执行此 VisitRequest 时，车辆抵达的地理位置。如果运单模型具有时长距离矩阵，则不得指定 arrivalLocation。

object (Waypoint)

执行此 VisitRequest 时车辆到达的航点。如果运单模型具有时长距离矩阵，则不得指定 arrivalWaypoint。

object (LatLng)

完成此 VisitRequest 后，车辆离开的地理位置。如果与 arrivalLocation 相同，则可以省略。如果运单模型具有时长距离矩阵，则不得指定 departureLocation。

object (Waypoint)

完成此 VisitRequest 后，车辆离开的航点。如果与 arrivalWaypoint 相同，则可以省略。如果运单模型具有时长距离矩阵，则不得指定 departureWaypoint。

string

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

object (TimeWindow)

限制访问的到达时间的时间范围。请注意，车辆可能会在到达时间窗口之外离开，即到达时间 + 持续时间无需在时间窗口内。如果车辆在 TimeWindow.start_time之前抵达，您可能需要等待一段时间。

如果缺少 TimeWindow，则表示车辆可以随时进行此访问。

时间窗口必须是不相交的，即所有时间窗口都不得与其他时间窗口重叠或相邻，并且顺序必须递增。

仅当存在单个时间范围时才能设置 costPerHourAfterSoftEndTime 和 softEndTime。

string (Duration format)

访问持续时间，即车辆从到达到出发所花费的时间（将添加到可能的等待时间中；请参阅 timeWindows）。

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

number

在车辆行驶路线上处理此访问请求的费用。此属性可用于为不同的商品自提或配送选项支付不同的费用。此费用的单位必须与“Shipment.penalty_cost”相同，且不得为负数。

map (key: string, value: object (Load))

加载此访问请求的需求。这类似于 Shipment.load_demands 字段，只不过它仅适用于此 VisitRequest，而不是整个 Shipment。此处列出的需求已添加到“Shipment.load_demands”中列出的需求。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

string

指定访问的类型。系统可能会据此分配车辆完成此次访问所需的额外时间（请参阅Vehicle.extra_visit_duration_for_visit_type）。

一个类型只能出现一次。

string

为此 VisitRequest 指定标签。在响应中，此标签会在相应 ShipmentRoute.Visit 中报告为 visitLabel。

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。

boolean

可选。表示此航点的位置优先让车辆停靠在道路的某一侧。设置此值后，路线会经过相应位置，这样车辆才能在偏离道路中心的道路一侧停靠。此选项不适用于“步行”出行方式。

object (Location)

使用地理坐标指定的点，包含可选标题。

string

与航点相关联的地图注点地点 ID。

object (LatLng)

航点的地理坐标。

integer

与交通流动方向相关联的罗盘航向。此值用于指定上车点和下车点的公路一侧。方位值的范围为 0 到 360，其中 0 指定正北方位，90 指定正北方方向，依此类推。

string (Timestamp format)

硬性时间范围的开始时间。如果未指定，则将设置为 ShipmentModel.global_start_time。

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

string (Timestamp format)

硬性时间范围的结束时间。如果未指定，则将设置为 ShipmentModel.global_end_time。

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

string (Timestamp format)

时间范围的软启动时间。

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

string (Timestamp format)

时间范围的软结束时间。

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

number

如果事件在 softStartTime 之前发生，则每小时的费用与模型中的其他费用相加，计算公式如下：

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

该开销必须为正数，并且只有在设置了 softStartTime 时才能设置该字段。

number

如果事件发生在 softEndTime 之后，则每小时的费用与模型中的其他费用相加，计算公式如下：

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

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

string

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

enum (TravelMode)

会影响车辆可使用的道路及其速度的出行方式。另请参阅 travelDurationMultiple。

object (LatLng)

车辆在取走任何货物之前出发的地理位置。如果未指定，车辆会在首次上车点启动。如果运单模型具有时长和距离矩阵，则不得指定 startLocation。

object (Waypoint)

表示车辆在取走任何货物前出发的地理位置的航点。如果 startWaypoint 和 startLocation 均未指定，则车辆会在首次上车点启动。如果运单模型具有时长和距离矩阵，则不得指定 startWaypoint。

object (LatLng)

车辆在最后一次行驶 VisitRequest后结束的地理位置。如果未指定，车辆的 ShipmentRoute 会在完成最后一个 VisitRequest 后立即结束。如果运单模型具有时长和距离矩阵，则不得指定 endLocation。

object (Waypoint)

表示车辆在结束上一个VisitRequest后结束的地理位置的航点。如果 endWaypoint 和 endLocation 均未指定，则车辆的 ShipmentRoute 将在完成最后一个 VisitRequest 后立即结束。如果运单模型具有时长和距离矩阵，则不得指定 endWaypoint。

string

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

不允许使用空字符串或重复字符串。

string

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

不允许使用空字符串或重复字符串。

object (TimeWindow)

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

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

仅当存在单个时间范围时才能设置 costPerHourAfterSoftEndTime 和 softEndTime。

object (TimeWindow)

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

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

仅当存在单个时间范围时才能设置 costPerHourAfterSoftEndTime 和 softEndTime。

enum (UnloadingPolicy)

已在车辆上强制执行卸载政策。

map (key: string, value: object (LoadLimit))

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

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

number

车辆费用：所有费用相加，且必须与“Shipment.penalty_cost”处于同一单位。

车辆路线的每小时费用。该费用适用于相应路线的总时间，包括行程时间、等候时间和到访时间。使用 costPerHour 而不是仅使用 costPerTraveledHour 可能会导致额外的延迟。

number

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

number

车辆行驶路线的每公里费用。此开销会应用于 ShipmentRoute.transitions 中报告的距离，而不适用于从单个 VisitRequest 的 arrivalLocation 到 departureLocation 隐式传输的任何距离。

number

如果此车辆用于处理运单，则会收取固定费用。

boolean

此字段仅适用于相应车辆路线不提供任何运单的车辆。用于指明在这种情况下是否应将车辆视为二手。

如果为 true，则即使车辆不提供任何装运，也会从起点到终点位置，以及从起点开始产生的时间和距离成本 -->包括结束旅行

否则，它不会从出发位置前往目的地，并且没有为此车辆安排breakRule或延迟（从 TransitionAttributes开始）。在这种情况下，车辆的 ShipmentRoute 不包含车辆索引和标签以外的任何信息。

object (DurationLimit)

应用于车辆路线的总时长的限制。在给定的 OptimizeToursResponse 中，车辆的路线时长是其 vehicleEndTime 和 vehicleStartTime 之间的差值。

object (DurationLimit)

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

object (DistanceLimit)

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

map (key: string, value: string (Duration format))

指定从访问类型字符串到持续时间的映射。时长是指在指定了 visitTypes 的访问时获取的 VisitRequest.duration 之外的时间。如果指定了 costPerHour，这种额外的访问持续时间会增加费用。键（即 visitTypes）不能为空字符串。

如果访问请求有多种类型，系统会为地图中的每种类型分别添加一个时长。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

object (BreakRule)

说明要在这辆车上强制执行的休息时间表。如果留空，系统不会为此车辆安排任何休息时间。

string

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

boolean

如果设为 true，usedIfRouteIsEmpty 必须为 false，这辆车将保持未使用状态。

如果配送由 injectedFirstSolutionRoutes 中忽略的车辆执行，第一个解决方案中会跳过该操作，但可以在响应中执行该操作。

如果配送由忽略的车辆在 injectedSolutionConstraint 中执行，并且任何相关的取货/送货限制被限制为留在车辆上（即未放宽到 RELAX_ALL_AFTER_THRESHOLD 级），则响应中会跳过该操作。如果某个运单包含非空的 allowedVehicleIndices 字段，并且所有允许的车辆都被忽略，则系统在响应中会跳过该运单。

number

指定可用于延长或缩短此车辆行程时间的乘法系数。例如，将此值设为 2.0 表示车辆速度较慢，其行程时间是标准车辆的两倍。此值不会影响访问持续时间。如果指定了 costPerHour 或 costPerTraveledHour，则会影响费用。必须在 [0.001, 1000.0] 范围内。如果未设置，则车辆为标准车辆，系统会视为 1.0 乘数。

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

另请参阅下面的 extraVisitDurationForVisitType。

string (int64 format)

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

number

如果车辆沿这辆车路线的负载超过 softMaxLoad，则适用以下费用罚款（每辆车只能收费一次）：(负载 - softMaxLoad) * costPerUnitAboveSoftMax。所有费用相加，且必须与Shipment.penalty_cost处于同一单位。

object (Interval)

车辆在路线起点的可接受装入间隔时间。

object (Interval)

车辆在路线终点的可接受装运间隔。

string (int64 format)

可接受的最大负载量。

string (int64 format)

可接受的最小负载。必须大于或等于 0。如果同时指定这两者，则 min 必须 ≤ max。

string (int64 format)

可接受的最大负载。必须大于或等于 0。如果未指定最大负载，则不受此消息的限制。如果同时指定这两者，则 min 必须 ≤ max。

string (Duration format)

将时长限制为不超过 maxDuration 的硬性限制。

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

string (Duration format)

软性限制，未强制实施时长上限，但如果违反，则会导致路线产生费用。此费用与模型中定义的其他费用相加，单位相同。

如果已定义，则 softMaxDuration 必须是非负数。如果还定义了 maxDuration，则 softMaxDuration 必须小于 maxDuration。

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

string (Duration format)

不强制执行时长上限的软性限制，但如果违反，会导致路线产生费用，即持续时间的二次方。此费用与模型中定义的其他费用相加，单位相同。

如果已定义，则 quadraticSoftMaxDuration 必须是非负数。如果还定义了 maxDuration，则 quadraticSoftMaxDuration 必须小于 maxDuration，且差值不得大于一天：

maxDuration - quadraticSoftMaxDuration <= 86400 seconds

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

number

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

  costPerHourAfterSoftMax * (duration - softMaxDuration)

费用必须是非负数。

number

违反 quadraticSoftMaxDuration 阈值时产生的每平方小时费用。

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

  costPerSquareHourAfterQuadraticSoftMax *
  (duration - quadraticSoftMaxDuration)^2

费用必须是非负数。

string (int64 format)

将距离限制为不超过 maxMeters 的硬性限制。上限必须是非负数。

string (int64 format)

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

如果定义的 softMaxMeters 必须小于 maxMeters，则必须为非负数。

number

如果距离超过 softMaxMeters 的上限，则产生的每公里费用。如果距离低于上限，则额外费用为 0，否则用于计算费用的公式如下所示：

  (distanceMeters - softMaxMeters) / 1000.0 *
  costPerKilometerAboveSoftMax.

费用必须是非负数。

object (BreakRequest)

插播时间点的顺序。请参阅 BreakRequest 消息。

object (FrequencyConstraint)

可能需要支付多个FrequencyConstraint。它们必须都满足此 BreakRule 的 BreakRequest。请参阅 FrequencyConstraint。

string (Timestamp format)

必需。广告插播时间点开始处的下限（含边界值）。

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

string (Timestamp format)

必需。插播时间点开始时的上限（含边界值）。

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

string (Duration format)

必需。广告插播时长下限。必须为正值。

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

string (Duration format)

必需。此限制条件的最短广告插播时长。非负数。请参阅 FrequencyConstraint 的说明。

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

string (Duration format)

必需。路线中至少部分间隔 duration >= minBreakDuration 内的任何时间段的允许跨度上限。必须为正值。

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

object (Row)

指定时长和距离矩阵的行。它包含的元素数量必须与 ShipmentModel.duration_distance_matrix_src_tags 一样多。

string

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

每次车辆启动都必须与一个矩阵完全一致，即其中一个 startTags 字段必须与矩阵（且仅限该矩阵）的 vehicleStartTag 匹配。

所有矩阵的 vehicleStartTag 都必须不同。

string (Duration format)

给定行的时长值。它包含的元素数量必须与 ShipmentModel.duration_distance_matrix_dst_tags 一样多。

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

number

给定行的距离值。如果模型中的距离没有任何费用或约束条件，则可以留空；否则，它的元素数量必须与 durations 相同。

string

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

当来源访问或车辆启动匹配时，仅当其 VisitRequest.tags 或 Vehicle.start_tags 包含 srcTag 或不包含 excludedSrcTag（具体取决于这两个字段中哪个字段为非空）时匹配。

string

请参阅 srcTag。“srcTag”和“excludedSrcTag”必须有且不得为空。

string

当目的地访问或车辆结束与 VisitRequest.tags 或 Vehicle.end_tags 包含 dstTag 或不包含 excludedDstTag 时匹配（具体取决于这两个字段中哪个字段不为空）。

string

请参阅 dstTag。“dstTag”和“excludedDstTag”必须有且不得为空。

number

指定执行此转换的费用。此费用与模型中的其他所有费用位于同一单位中，并且不得为负数。该费用在所有其他现有费用的基础上加收。

number

指定对执行此过渡时行驶的距离应用的每公里费用。此值等于车辆上指定的任何 Vehicle.cost_per_kilometer。

object (DistanceLimit)

指定执行此转场时移动的距离限制。

自 2021 年 6 月起，仅支持软性限额。

string (Duration format)

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

这种延迟总是发生在完成来源访问之后和开始目标访问之前。

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

string

不兼容的类型列表。列出的 shipment_types 不同的两件运单是“不兼容”的。

enum (IncompatibilityMode)

应用于不兼容的模式。

string

dependentShipmentTypes要求的备选运单类型的列表。

string

对于所有属于“dependentShipmentTypes”字段的运单，同一条航线上必须有至少 1 个类型为 requiredShipmentTypeAlternatives 的运单。

注意：不允许使用导致 shipmentType 依赖于自身的要求链。

enum (RequirementMode)

应用于要求的模式。

boolean

指明其是否为“第一个”事件是交付事件。

boolean

指示“第二个”事件是交付事件。

string (Duration format)

“第一个”和“second”事件。它可以为负值。

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

integer

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

integer

“秒”的装运索引事件。必须指定此字段。