ShipmentModel

string

用户为运输订单定义的显示名称。此字符串不得超过 63 个字符，并且可以使用 UTF-8 字符。

object (VisitRequest)

与运输订单关联的一组取件选项。如果未指定，车辆只需访问与送货地点对应的地点即可。

object (VisitRequest)

与运输订单关联的一组配送替代方案。如果未指定，车辆只需访问与上车点对应的地点即可。

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

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

integer

可能执行此运输的车辆组。如果为空，则所有车辆都可以执行此操作。车辆由 ShipmentModel 的 vehicles 列表中的编号指定。

number

指定使用每辆车辆运送此运输时产生的费用。如果指定了，则必须具有以下任一属性：

• 与 costsPerVehicleIndices 具有相同数量的元素。costsPerVehicle[i] 对应于该型号的车辆 costsPerVehicleIndices[i]。
• 元素数量与模型中的车辆数量相同。第 i 个元素对应于该型号的车辆 #i。

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

integer

应用 costsPerVehicle 的车辆的索引。如果不为空，则必须与 costsPerVehicle 具有相同数量的元素。车辆编号不得重复指定。如果某辆车辆从 costsPerVehicleIndices 中排除，则其费用为零。

string (Duration format)

指定与从上车点到下车点的最短路线相比的绝对绕道时间上限。如果指定，则必须为非负数，并且运输必须至少包含一个上门取件和一个送货。

例如，设 t 为从所选的取件替代方案直接前往所选的送货替代方案所需的最短时间。然后，设置 pickupToDeliveryAbsoluteDetourLimit 会强制执行以下操作：

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

如果同一运输中同时指定了相对上限和绝对上限，系统会对每个可能的取件/送货对使用更严格的上限。自 2017 年 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

指定与从上车点到下车点的最短路径相比的最大相对绕路时间。如果指定，则必须为非负数，并且运输必须至少包含一个上门取件和一个送货。

例如，设 t 为从所选的取件替代方案直接前往所选的送货替代方案所需的最短时间。然后，设置 pickupToDeliveryRelativeDetourLimit 会强制执行以下操作：

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

如果同一运输中同时指定了相对上限和绝对上限，系统会对每个可能的取件/送货对使用更严格的上限。自 2017 年 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 中列出的需求。

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 (RouteModifiers)

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

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 字段的键一致。如果此映射中不存在给定键，则相应容量将被视为无限。

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 字符串到时长的映射。时长是指在使用指定 visitTypes 进行访问时，除了 VisitRequest.duration 之外要花费的时间。如果指定了 costPerHour，则此额外的访问时长会增加费用。键（即 visitTypes）不能是空字符串。

如果访问请求具有多种类型，系统会在映射中为每种类型添加时长。

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。

boolean

指定是否在合理情况下避开收费公路。系统会优先选择不含收费道路的路线。仅适用于机动化出行方式。

boolean

指定是否在合理情况下避开高速公路。系统会优先选择不含高速公路的路线。仅适用于机动化出行方式。

boolean

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

boolean

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

string (int64 format)

负载的软上限。请参阅 costPerUnitAboveSoftMax。

number

如果此车辆的路线上的载荷超出 softMaxLoad，则会应用以下费用惩罚（每辆车仅应用一次）：(load - softMaxLoad) * costPerUnitAboveSoftMax。所有费用相加，并且必须与 Shipment.penalty_cost 采用相同的单位。

object (Interval)

车辆在路线起点处的可接受载荷间隔。

object (Interval)

车辆在路线结束时可接受的载荷间隔。

string (int64 format)

可接受的最大负载量。

string (int64 format)

可接受的最低负载。必须大于等于 0。如果同时指定了 min 和 max，则 min 必须小于等于 max。

string (int64 format)

可接受的最大负载。必须大于等于 0。如果未指定，则此消息不会限制最大负载。如果同时指定了 min 和 max，则 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），公式如下：

  min(distanceMeters, softMaxMeters) / 1000.0 *
  costPerKilometerBelowSoftMax.

routeDistanceLimit 不支持此费用。

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 匹配）。

所有矩阵都必须具有不同的 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 字段中类型为 dependentShipmentTypes 的所有运输，都要求在同一路线上至少访问一个类型为 requiredShipmentTypeAlternatives 的运输。

注意：不允许出现 shipmentType 依赖于自身的一系列要求。

enum (RequirementMode)

应用于相应要求的模式。

boolean

指明“第一个”事件是否为传送事件。

boolean

指示“第二个”事件是否为传送事件。

string (Duration format)

“first”和“second”事件之间的偏移。可以为负数。

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

integer

“first”事件的配送指数。必须指定此字段。

integer

“第二个”事件的配送编号。必须指定此字段。