ShipmentModel

装运模型包含一组装运，这些装运必须由一组车辆执行，同时最大限度地降低总成本，即以下总和：

  • 规划车辆路线的费用（每总时间费用、每次行程时间费用和所有车辆的固定费用的总和）。
  • 未履行的发货处罚。
  • 全球运单产生的费用
JSON 表示法 
{
  "shipments": [
    {
      object (Shipment)
    }
  ],
  "vehicles": [
    {
      object (Vehicle)
    }
  ],
  "globalStartTime": string,
  "globalEndTime": string,
  "globalDurationCostPerHour": number,
  "durationDistanceMatrices": [
    {
      object (DurationDistanceMatrix)
    }
  ],
  "durationDistanceMatrixSrcTags": [
    string
  ],
  "durationDistanceMatrixDstTags": [
    string
  ],
  "transitionAttributes": [
    {
      object (TransitionAttributes)
    }
  ],
  "shipmentTypeIncompatibilities": [
    {
      object (ShipmentTypeIncompatibility)
    }
  ],
  "shipmentTypeRequirements": [
    {
      object (ShipmentTypeRequirement)
    }
  ],
  "precedenceRules": [
    {
      object (PrecedenceRule)
    }
  ],
  "maxActiveVehicles": integer
}
字段
shipments[]

object (Shipment)

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

object (Vehicle)

可用于到访地点的一组车辆。
globalStartTime

string (Timestamp format)

模型的全局开始时间和结束时间：凡是超出此范围的时间均不会被视为有效。

模型的时间跨度必须少于一年，即 globalEndTime 和 globalStartTime 之间的间隔必须在 31536000 秒以内。

使用 cost_per_*hour 字段时，您可能希望将此时间范围设置为较短的时间间隔以提高性能（例如，如果为某一天建模，则应将全局时间限制设置为该日期）。如果未设置，则默认为 1970 年 1 月 1 日 00:00:00 UTC（即秒：0，nanos：0）。

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

string (Timestamp format)

如果未设置，则默认使用世界协调时间 (UTC) 1971 年 1 月 1 日 00:00:00（即秒：31536000，nanos：0）。

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

number

整体方案的“全球时长”是指所有车辆的最早有效开始时间和最新有效结束时间之间的差值。例如，用户可以为该数量指定每小时费用，以尝试进行优化，从而尽可能缩短作业时间。此费用必须与“Shipment.penalty_cost”采用同一单位。
durationDistanceMatrices[]

object (DurationDistanceMatrix)

指定模型中使用的持续时间和距离矩阵。如果此字段为空，系统将改用 Google 地图或测地距离，具体取决于 useGeodesicDistances 字段的值。如果不为空，则 useGeodesicDistances 不得为 true，且 durationDistanceMatrixSrcTags 和 durationDistanceMatrixDstTags 均不得为空。

用法示例：

  • 有两个位置：locA 和 locB。
  • 1 辆车从 locA 出发，到 locA 结束
  • 在 locB 有 1 个自提到访请求。
model {
  vehicles { startTags: "locA"  endTags: "locA" }
  shipments { pickups { tags: "locB" } }
  durationDistanceMatrixSrcTags: "locA"
  durationDistanceMatrixSrcTags: "locB"
  durationDistanceMatrixDstTags: "locA"
  durationDistanceMatrixDstTags: "locB"
  durationDistanceMatrices {
    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 结束
  • 使用“慢速”矩阵，1 辆车从 locB 出发，到 locB 结束
  • 1 辆车使用“快速”矩阵，从 locB 出发，到 locB 结束
  • 位于 locC 的 1 个自提到访请求。
model {
  vehicles { startTags: "locA" endTags: "locB" startTags: "fast" }
  vehicles { startTags: "locB" endTags: "locB" startTags: "slow" }
  vehicles { startTags: "locB" endTags: "locB" startTags: "fast" }
  shipments { pickups { tags: "locC" } }
  durationDistanceMatrixSrcTags: "locA"
  durationDistanceMatrixSrcTags: "locB"
  durationDistanceMatrixSrcTags: "locC"
  durationDistanceMatrixDstTags: "locB"
  durationDistanceMatrixDstTags: "locC"
  durationDistanceMatrices {
    vehicleStartTag: "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
    }
  }
  durationDistanceMatrices {
    vehicleStartTag: "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
    }
  }
}
durationDistanceMatrixSrcTags[]

string

标记用于定义时长和距离矩阵的来源；durationDistanceMatrices(i).rows(j) 用于定义从带有 durationDistanceMatrixSrcTags(j) 标记的访问到矩阵 i 中其他访问的持续时间和距离。

标记对应于 VisitRequest.tags 或 Vehicle.start_tags。指定的 VisitRequest 或 Vehicle 必须与此字段中的一个标记完全匹配。请注意，Vehicle 的来源标记、目标标记和矩阵标记可以相同；类似地，VisitRequest 的来源标记和目标标记可以相同。所有标记不得相同，且不得为空字符串。如果此字段不为空，则“durationDistanceMatrices”不得为空。
durationDistanceMatrixDstTags[]

string

用于定义时长和距离矩阵目的地的标记；durationDistanceMatrices(i).rows(j).durations(k)（durationDistanceMatrices(i).rows(j).meters(k)) 定义了从矩阵 i 中带有 durationDistanceMatrixSrcTags(j) 标记的访问到带有 durationDistanceMatrixDstTags(k) 标记的访问之间的行程时长（距离）。

标记对应于 VisitRequest.tags 或 Vehicle.start_tags。指定的 VisitRequest 或 Vehicle 必须与此字段中的一个标记完全匹配。请注意，Vehicle 的来源标记、目标标记和矩阵标记可以相同；类似地，VisitRequest 的来源标记和目标标记可以相同。所有标记不得相同，且不得为空字符串。如果此字段不为空，则“durationDistanceMatrices”不得为空。
transitionAttributes[]

object (TransitionAttributes)

添加到模型中的过渡属性。
shipmentTypeIncompatibilities[]

object (ShipmentTypeIncompatibility)

不兼容的 shipping_types [运单类型] 集（请参阅 ShipmentTypeIncompatibility）。
shipmentTypeRequirements[]

object (ShipmentTypeRequirement)

一组 shipmentType 要求（请参阅 ShipmentTypeRequirement）。
precedenceRules[]

object (PrecedenceRule)

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

integer

限制活跃车辆的最大数量。如果车辆的路线至少执行一次装运，则该车辆处于有效状态。当司机人数少于车辆并且车队不均等时，这可用于限制路线数量。优化功能会选择最适合的车辆子集。必须为正数。

发货

单件商品的运输（从提货到送货）。要想将货运视为已履行，专用车辆必须前往其中一个取货地点（并相应地减少备用容量），稍后再前往其中一个送货地点（并相应地重新增加备用容量）。

JSON 表示法 
{
  "displayName": string,
  "pickups": [
    {
      object (VisitRequest)
    }
  ],
  "deliveries": [
    {
      object (VisitRequest)
    }
  ],
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "allowedVehicleIndices": [
    integer
  ],
  "costsPerVehicle": [
    number
  ],
  "costsPerVehicleIndices": [
    integer
  ],
  "pickupToDeliveryAbsoluteDetourLimit": string,
  "pickupToDeliveryTimeLimit": string,
  "shipmentType": string,
  "label": string,
  "ignore": boolean,
  "penaltyCost": number,
  "pickupToDeliveryRelativeDetourLimit": number
}
字段
displayName

string

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

object (VisitRequest)

与运单相关联的备选自提选项集。如果未指定，车辆只需前往与货品对应的营业地点。
deliveries[]

object (VisitRequest)

与运单相关联的备选递送方式集。如果未指定，车辆只需造访与上车点对应的位置。
loadDemands

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

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

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

integer

可执行此装运的车辆组。如果为空，则所有车辆都可以执行这项操作。车辆由 ShipmentModel 的 vehicles 列表中的索引指定。
costsPerVehicle[]

number

指定每辆车送达此运单时产生的费用。如果指定，则必须包含以下其中一个：

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

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

integer

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

string (Duration format)

指定与从自提到送货的最短路径相比，最大绝对绕行时间。如果指定，此值必须是非负数，并且装运必须至少包含自提和配送。

例如，我们将 t 设为从所选自提备选方案直接到所选备选配送方式所用的最短时间。然后，设置 pickupToDeliveryAbsoluteDetourLimit 会强制执行：

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

如果为同一件运单同时指定了相对限制和绝对限制，则系统会对每个可能的自提/送货对使用限制性更强的限制。自 2017/10 起，仅当行程时长与车辆无关时，才支持绕行功能。

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

string (Duration format)

指定从自提开始到发货开始交付的最长时长。如果指定，此值必须是非负数，并且装运必须至少包含自提和配送。这不取决于选择自提和送货的替代车辆，也不取决于车辆的速度。可以同时指定最大绕行限制：解决方案将遵循这两个规范。

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

string

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

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

string

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

boolean

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

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

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

number

如果装运未完成，则此罚金会加到航线总费用中。如果客户访问了某件自提和配送替代选项，则该运单会被视为已完成。费用可以用模型中所有其他费用相关字段所用的单位表示，并且必须为正数。

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

number

指定最大相对绕行时间（相对于从取货到送货的最短路径）。如果指定，此值必须是非负数，并且装运必须至少包含自提和配送。

例如，我们将 t 设为从所选自提备选方案直接到所选备选配送方式所用的最短时间。然后，设置 pickupToDeliveryRelativeDetourLimit 会强制执行：

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

如果为同一件运单同时指定了相对限制和绝对限制，则系统会对每个可能的自提/送货对使用限制性更强的限制。自 2017/10 起，仅当行程时长与车辆无关时，才支持绕行功能。

VisitRequest

请求由车辆完成的上门服务：车辆具有地理位置（或两个，见下文）、打开和关闭时间（以时间范围表示）以及服务持续时间（车辆抵达上车点或下车点后所花费的时间）。

JSON 表示法 
{
  "arrivalLocation": {
    object (LatLng)
  },
  "arrivalWaypoint": {
    object (Waypoint)
  },
  "departureLocation": {
    object (LatLng)
  },
  "departureWaypoint": {
    object (Waypoint)
  },
  "tags": [
    string
  ],
  "timeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "duration": string,
  "cost": number,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "visitTypes": [
    string
  ],
  "label": string
}
字段
arrivalLocation

object (LatLng)

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

object (Waypoint)

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

object (LatLng)

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

object (Waypoint)

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

string

指定附加到访问请求的标记。字符串不得为空或重复。
timeWindows[]

object (TimeWindow)

用于限制访问的到达时间的时间范围。请注意，车辆可能会在到达时间范围之外出发，也就是说，到达时间 + 时长不必在某个时间范围内。如果车辆在 TimeWindow.start_time之前到达，您可能需要等待一段时间。

TimeWindow 不存在表示车辆可以随时执行此次访问。

时间窗口必须不相交，即时间窗口不能与其他时间窗口重叠或相邻，并且必须按递增顺序排列。

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

string (Duration format)

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

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

number

处理相应行车路线的这项访问请求所需的费用。可用于为每种备选的自提或配送订单支付不同的费用。此费用必须与“Shipment.penalty_cost”处于同一单位，且不得为负数。
loadDemands

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

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

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

string

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

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

string

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

LatLng

表示纬度/经度对的对象。该对象以一对双精度数表示，分别代表纬度度数和经度度数。除非另有说明，否则该对象必须符合 WGS84 标准。值必须介于标准化范围内。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

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

number

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

关键点

封装航点。航点用于标记 VisitRequest 的到达和出发位置，以及车辆的起点和终点位置。

JSON 表示法 
{
  "sideOfRoad": boolean,

  // Union field location_type can be only one of the following:
  "location": {
    object (Location)
  },
  "placeId": string
  // End of list of possible types for union field location_type.
}
字段
sideOfRoad

boolean

可选。表示此航点的位置应首选让车辆停在道路的某一侧。设置此值后，路线将穿过该位置，以便车辆能够在该位置偏向于道路中心的那一侧道路。此选项不适用于“步行”出行方式。
联合字段 location_type。表示位置的不同方式。location_type 只能是下列其中一项：
location

object (Location)

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

string

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

位置

封装位置（地理点和可选标题）。

JSON 表示法 
{
  "latLng": {
    object (LatLng)
  },
  "heading": integer
}
字段
latLng

object (LatLng)

航点的地理坐标。
heading

integer

与车流方向相关联的罗盘航向。此值用于指定上车点和下车点的一侧道路。方向值可以是 0 到 360，其中 0 表示正北方位，90 表示正东方向，以此类推。

TimeWindow

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

硬时间范围边界 startTime 和 endTime 会强制执行事件的最早和最新时间，以便 startTime <= event_time <= endTime。软时间窗口下限 softStartTime 通过产生与 softStartTime 事件发生之前的时间成比例的费用，表示事件在 softStartTime 期间或之后发生的偏好。软时间窗口上限 softEndTime 表示偏好在 softEndTime 当天或之前发生的事件，因为发生的费用与 softEndTime 事件发生后的时间成正比。startTime、endTime、softStartTime 和 softEndTime 应在全球时间限制内（请参阅 ShipmentModel.global_start_time 和 ShipmentModel.global_end_time），并应遵循：

  0 <= `startTime` <= `softStartTime` <= `endTime` and
  0 <= `startTime` <= `softEndTime` <= `endTime`.
JSON 表示法 
{
  "startTime": string,
  "endTime": string,
  "softStartTime": string,
  "softEndTime": string,
  "costPerHourBeforeSoftStartTime": number,
  "costPerHourAfterSoftEndTime": number
}
字段
startTime

string (Timestamp format)

硬时间窗口的开始时间。如果未指定，系统会将其设置为 ShipmentModel.global_start_time。

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

string (Timestamp format)

硬时间窗口结束时间。如果未指定，系统会将其设置为 ShipmentModel.global_end_time。

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

string (Timestamp format)

时间范围的软启动时间。

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

string (Timestamp format)

时间范围的软结束时间。

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

number

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

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

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

number

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

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

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

交通工具

为遇到运输问题的车辆建模。解决运输问题后，系统会为此车辆构建一条从 startLocation 开始、到 endLocation 结束的路线。路线是指一系列访问（请参阅 ShipmentRoute）。

JSON 表示法 
{
  "displayName": string,
  "travelMode": enum (TravelMode),
  "startLocation": {
    object (LatLng)
  },
  "startWaypoint": {
    object (Waypoint)
  },
  "endLocation": {
    object (LatLng)
  },
  "endWaypoint": {
    object (Waypoint)
  },
  "startTags": [
    string
  ],
  "endTags": [
    string
  ],
  "startTimeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "endTimeWindows": [
    {
      object (TimeWindow)
    }
  ],
  "unloadingPolicy": enum (UnloadingPolicy),
  "loadLimits": {
    string: {
      object (LoadLimit)
    },
    ...
  },
  "costPerHour": number,
  "costPerTraveledHour": number,
  "costPerKilometer": number,
  "fixedCost": number,
  "usedIfRouteIsEmpty": boolean,
  "routeDurationLimit": {
    object (DurationLimit)
  },
  "travelDurationLimit": {
    object (DurationLimit)
  },
  "routeDistanceLimit": {
    object (DistanceLimit)
  },
  "extraVisitDurationForVisitType": {
    string: string,
    ...
  },
  "breakRule": {
    object (BreakRule)
  },
  "label": string,
  "ignore": boolean,
  "travelDurationMultiple": number
}
字段
displayName

string

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

enum (TravelMode)

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

object (LatLng)

取货前车辆所处的地理位置。如果未指定，车辆将在首次上车点启动。如果运单模型具有时长和距离矩阵，则不得指定 startLocation。
startWaypoint

object (Waypoint)

表示车辆在提取任何货物之前开始位置处的航点。如果 startWaypoint 和 startLocation 均未指定，则车辆会在第一次上车时启动。如果运单模型具有时长和距离矩阵，则不得指定 startWaypoint。
endLocation

object (LatLng)

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

object (Waypoint)

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

string

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

字符串不得为空或重复。
endTags[]

string

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

字符串不得为空或重复。
startTimeWindows[]

object (TimeWindow)

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

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

仅当存在一个时间范围时，才能设置 costPerHourAfterSoftEndTime 和 softEndTime。
endTimeWindows[]

object (TimeWindow)

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

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

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

enum (UnloadingPolicy)

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

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

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

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

number

车辆费用：所有费用相加，且必须与 Shipment.penalty_cost 在同一单位内。

行车路线的每小时费用。此费用会计入相应路线所需的总时间，包括行程时间、等待时间和访问时间。使用 costPerHour（而不仅仅是 costPerTraveledHour）可能会导致额外的延迟。
costPerTraveledHour

number

行车路线的每行驶小时费用。此费用仅针对相应路线所花费的行程时间（即在 ShipmentRoute.transitions 中报告的时间），不包括等待时间和访问时间。
costPerKilometer

number

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

number

若使用此车辆处理运单，会收取固定费用。
usedIfRouteIsEmpty

boolean

此字段仅适用于车辆路线中没有任何货物的车辆。用于指示在这种情况下是否应将车辆视为已使用。

如果为 true，即使车辆不提供任何货运，车辆也会从起点到终点位置，并且将开始产生的时间和距离费用考虑在内 --> 结束行程。

否则，车辆不会从出发地出发前往结束位置，也不会为这辆车安排breakRule或延迟（从TransitionAttributes开始）。在本例中，车辆的 ShipmentRoute 不包含除车辆索引和标签以外的任何信息。
routeDurationLimit

object (DurationLimit)

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

object (DurationLimit)

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

object (DistanceLimit)

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

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

指定从 accessTypes 字符串到时长的映射。该时长是对具有指定 visitTypes 的访问执行的时间与 VisitRequest.duration 之和。如果指定了 costPerHour，这一额外的访问持续时间会增加费用。键（即 visitTypes）不能为空字符串。

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

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

object (BreakRule)

描述要对此车辆强制执行的广告插播时间表。如果留空，系统将不会为此车辆安排任何休息时间。
label

string

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

boolean

如果为 true，则“usedIfRouteIsEmpty”必须为 false，并且这辆车将保持未使用状态。

如果运单由 injectedFirstSolutionRoutes 中被忽略的车辆执行，则在第一个解决方案中会跳过该运单，但可以在响应中自由执行。

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

number

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

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

另请参阅下面的 extraVisitDurationForVisitType。

TravelMode

可供车辆使用的出行方式。

这些路线应该是 Google Maps Platform Routes Preferred API 出行方式的一部分，请参阅：https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode。

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

UnloadingPolicy

关于如何卸载车辆的政策。仅适用于同时提供自提和配送选项的运单。

除此之外，在沿途任何地点（unloadingPolicy 除外）的运输无需支付。

枚举
UNLOADING_POLICY_UNSPECIFIED 未指定的卸载政策；必须在相应自提商品之后送达。
LAST_IN_FIRST_OUT 送货必须和取货顺序相反
FIRST_IN_FIRST_OUT 送货订单必须与自提订单相同

LoadLimit

定义适用于车辆的负载限制，例如“这辆卡车只能装载 3500 千克”。请参阅loadLimits。

JSON 表示法 
{
  "softMaxLoad": string,
  "costPerUnitAboveSoftMax": number,
  "startLoadInterval": {
    object (Interval)
  },
  "endLoadInterval": {
    object (Interval)
  },
  "maxLoad": string
}
字段
softMaxLoad

string (int64 format)

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

number

如果车辆沿途的负载超过 softMaxLoad，将适用以下成本处罚（每辆车只收取一次）：(负载 - softMaxLoad) * costPerUnitAboveSoftMax。所有费用相加，必须与 Shipment.penalty_cost 在同一单位内。
startLoadInterval

object (Interval)

车辆在路线起点的可接受负载间隔。
endLoadInterval

object (Interval)

车辆在路线终点的可接受负载间隔。
maxLoad

string (int64 format)

可接受的最大负载。

间隔时间

可接受的负载量的间隔。

JSON 表示法 
{
  "min": string,
  "max": string
}
字段
min

string (int64 format)

可接受的最低负载。必须大于等于 0。如果两个值都指定，则“min”必须小于等于 max。
max

string (int64 format)

可接受的最大负载。必须大于等于 0。如果未指定，最大负载将不受此消息的限制。如果两个值都指定，则“min”必须小于等于 max。

DurationLimit

用于定义车辆路线持续时间上限的限值。可以是硬的，也可以是软的。

定义软限制字段时，必须同时定义软最高阈值及其相关费用。

JSON 表示法 
{
  "maxDuration": string,
  "softMaxDuration": string,
  "quadraticSoftMaxDuration": string,
  "costPerHourAfterSoftMax": number,
  "costPerSquareHourAfterQuadraticSoftMax": number
}
字段
maxDuration

string (Duration format)

有硬性限制，规定时长不得超过 maxDuration。

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

string (Duration format)

未强制执行时长上限的软性限制，但如果违反，路线就会产生费用。此费用与模型中定义的其他具有相同单位的费用相加。

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

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

string (Duration format)

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

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

maxDuration - quadraticSoftMaxDuration <= 86400 seconds

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

number

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

  costPerHourAfterSoftMax * (duration - softMaxDuration)

费用必须是非负数。
costPerSquareHourAfterQuadraticSoftMax

number

如果违反了 quadraticSoftMaxDuration 阈值，则每平方小时的费用。

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

  costPerSquareHourAfterQuadraticSoftMax *
  (duration - quadraticSoftMaxDuration)^2

费用必须是非负数。

DistanceLimit

定义可移动的最大距离的极限。可以是硬的，也可以是软的。

如果定义了软限制，则必须同时定义 softMaxMeters 和 costPerKilometerAboveSoftMax，且必须为非负数。

JSON 表示法 
{
  "maxMeters": string,
  "softMaxMeters": string,
  "costPerKilometerAboveSoftMax": number
}
字段
maxMeters

string (int64 format)

硬性限制将距离限制为最多 maxMeter。该限制必须是非负数。
softMaxMeters

string (int64 format)

软性限制不强制执行最大距离限制，但如果违反该限制，会导致费用加总到模型中定义的采用相同单位的其他费用。

如果已定义 softMaxMeter，则必须小于 maxMeter，且必须为非负数。
costPerKilometerAboveSoftMax

number

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

  (distanceMeters - softMaxMeters) / 1000.0 *
  costPerKilometerAboveSoftMax.

费用必须是非负数。

BreakRule

用于为车辆生成休息时间的规则（例如，午休）。休息是指连续一段时间，车辆会在当前位置保持空闲状态，无法执行任何访问操作。休息时间可能会：

  • 在两次访问之间的行程期间发生的转化（包括访问之前或之后的时间，而不是访问中间的时间），在这种情况下，它会延长访问之间的相应运送时间；
  • 或车辆启动前（车辆可能无法在休息期间启动），在这种情况下，车辆启动不会影响车辆的启动时间。
  • 或车辆结束之后（同上，显示的是车辆结束时间）。
JSON 表示法 
{
  "breakRequests": [
    {
      object (BreakRequest)
    }
  ],
  "frequencyConstraints": [
    {
      object (FrequencyConstraint)
    }
  ]
}
字段
breakRequests[]

object (BreakRequest)

中断顺序。请参阅 BreakRequest 消息。
frequencyConstraints[]

object (FrequencyConstraint)

可能需要遵守多项FrequencyConstraint。它们必须全部满足此 BreakRule 的 BreakRequest。请参阅 FrequencyConstraint。

BreakRequest

必须事先知道适用于每辆车的中断顺序（即它们的数量和顺序）。重复的 BreakRequest 按照它们必须出现的顺序定义该序列。它们的时间范围 (earliestStartTime / latestStartTime) 可能会重叠，但必须与顺序兼容（已选中）。

JSON 表示法 
{
  "earliestStartTime": string,
  "latestStartTime": string,
  "minDuration": string
}
字段
earliestStartTime

string (Timestamp format)

必需。广告插播开始处的下限（含此下限）。

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

string (Timestamp format)

必需。广告插播开始处的上限（含）。

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

string (Duration format)

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

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

FrequencyConstraint

可以通过强制设置最低广告插播频率，例如“每 12 小时必须至少休息 1 小时”，进一步限制上述插播时间点的频率和时长。假设可解释为“在 12 小时的任何滑动时间窗口中，必须至少有 1 个广告插播时间点（至少一小时），该示例可转换为以下 FrequencyConstraint：

{
   minBreakDuration { seconds: 3600 }         # 1 hour.
   maxInterBreakDuration { 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
JSON 表示法 
{
  "minBreakDuration": string,
  "maxInterBreakDuration": string
}
字段
minBreakDuration

string (Duration format)

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

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

string (Duration format)

必需。路线中任何间隔的跨度上限，其中不包含 duration >= minBreakDuration 的至少部分中断。必须为正值。

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

DurationDistanceMatrix

指定从到访和车辆出发位置到到访地点和车辆结束位置的时长和距离矩阵。

JSON 表示法 
{
  "rows": [
    {
      object (Row)
    }
  ],
  "vehicleStartTag": string
}
字段
rows[]

object (Row)

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

string

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

每个车辆出发位置必须正好匹配一个矩阵，即，startTags 字段中必须有且仅有一个矩阵必须与该矩阵的 vehicleStartTag（且仅限于该矩阵）匹配。

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

行

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

JSON 表示法 
{
  "durations": [
    string
  ],
  "meters": [
    number
  ]
}
字段
durations[]

string (Duration format)

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

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

number

给定行的距离值。如果模型中的距离没有费用或约束条件，则可以留空；否则，它必须具有与 durations 一样多的元素。

TransitionAttributes

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

JSON 表示法 
{
  "srcTag": string,
  "excludedSrcTag": string,
  "dstTag": string,
  "excludedDstTag": string,
  "cost": number,
  "costPerKilometer": number,
  "distanceLimit": {
    object (DistanceLimit)
  },
  "delay": string
}
字段
srcTag

string

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

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

string

请参阅 srcTag。srcTag 和 excludedSrcTag 中必须有一个不得为空。
dstTag

string

当目的地到访或车辆终点匹配时，如果其 VisitRequest.tags 或 Vehicle.end_tags 包含 dstTag 或不包含 excludedDstTag（具体取决于这两个字段中哪个不为空）。
excludedDstTag

string

请参阅 dstTag。dstTag 和 excludedDstTag 中必须有一个不得为空。
cost

number

指定执行此转换所需的费用。此单位与模型中的所有其他费用属于同一单位，且不能为负数。它是在所有其他现有费用基础上收取的。
costPerKilometer

number

指定在执行此转换时所行驶距离应用的每公里费用。它等于车辆上指定的任意 Vehicle.cost_per_kilometer。
distanceLimit

object (DistanceLimit)

指定执行此转换时行程距离的限制。

从 2021 年 6 月开始，仅支持软性限制。
delay

string (Duration format)

指定执行此转换时发生的延迟。

这种延迟始终发生在来源访问完成之后、目的地访问开始之前。

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

ShipmentTypeIncompatibility

根据发货类型指定发货间的不兼容问题。根据不兼容模式，在同一航线中显示不兼容的配送选项会受到限制。

JSON 表示法 
{
  "types": [
    string
  ],
  "incompatibilityMode": enum (IncompatibilityMode)
}
字段
types[]

string

不兼容的类型列表。所列两批货运的shipment_types不同是“不兼容”的。
incompatibilityMode

enum (IncompatibilityMode)

应用于不兼容的模式。

IncompatibilityMode

用于指定如何在同一航线上限制不兼容的运单的显示模式。

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

对于两件货物，其类型与“NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY”不兼容模式不兼容：

  • 如果两者都仅限自提（不送货）或仅送货（不送货），则不能共用同一辆车。
  • 如果其中一批货物有货，另一批货物有自提服务，且前一批货品在前一批货物被自提前送达，这两批货物可共用同一辆车。

ShipmentTypeRequirement

根据 shippingType 指定运单之间的要求。具体要求由要求模式定义。

JSON 表示法 
{
  "requiredShipmentTypeAlternatives": [
    string
  ],
  "dependentShipmentTypes": [
    string
  ],
  "requirementMode": enum (RequirementMode)
}
字段
requiredShipmentTypeAlternatives[]

string

dependentShipmentTypes要求的替代运单类型的列表。
dependentShipmentTypes[]

string

“dependentShipmentTypes”字段中类型的所有运单都要求在同一航线上至少访问一个类型为“requiredShipmentTypeAlternatives”的运单。

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

enum (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 与之前一样，不同之处在于，“依赖”发货的货物在送达时，其车辆上必须有“必需”的货物。

PrecedenceRule

两个事件（每个事件为提货或提货事件）之间的优先规则：“第二个”事件的开始日期必须在“第一个”事件开始后至少 offsetDuration。

多个优先级可以指代相同（或相关）事件，例如，“取货 B 发生在 A 交付之后”和“自提 C 发生在取货 B 之后”。

此外，只有在同时完成这两件运单时，才适用优先级，否则会被忽略。

JSON 表示法 
{
  "firstIsDelivery": boolean,
  "secondIsDelivery": boolean,
  "offsetDuration": string,
  "firstIndex": integer,
  "secondIndex": integer
}
字段
firstIsDelivery

boolean

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

boolean

指明“second”事件是否为传送。
offsetDuration

string (Duration format)

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

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

integer

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

integer

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