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 欄位時，建議您縮小時間間隔，藉此提升效能 (例如，如果模擬單一日，則應將全域時間限制設為當天)。如未設定，系統會預設使用世界標準時間 00:00:00 (世界標準時間)，1970 年 1 月 1 日 (亦即秒數：0，nanos: 0)。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
globalEndTime

string (Timestamp format)

如未設定，系統會預設使用世界標準時間 1971 年 1 月 1 日 00:00:00 (亦即秒數：31536000，nanos: 0)。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
globalDurationCostPerHour

number

整體計畫的「全球持續時間」，是指所有車輛的最早有效開始時間和最新有效結束時間之間的差異。舉例來說，使用者可以為該數量指定每小時費用，嘗試並嘗試盡可能早完成工作。這筆費用必須與 Shipment.penalty_cost 相同。
durationDistanceMatrices[]

object (DurationDistanceMatrix)

指定模型中使用的時間長度和距離矩陣。如果這個欄位空白，系統會根據 useGeodesicDistances 欄位的值，改用 Google 地圖或測地距離。如果不留空，useGeodesicDistances 不得為 true，durationDistanceMatrixSrcTags 和 durationDistanceMatrixDstTags 也都不能空白。

使用範例：

  • 共有兩個地點：locA 和 locB。
  • 1 輛車在 locA 後開始行駛路線，並於 locA 結束。
  • 1 個取貨造訪要求，位於 locB。
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 結束。
  • 1 個取貨造訪要求，位於 locC。
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) (resp. 使用 durationDistanceMatrixSrcTags(j) 標記 durationDistanceMatrixDstTags(k) 的造訪，durationDistanceMatrices(i).rows(j).meters(k)) 定義從造訪到造訪所經過的時間 (距離距離)，矩陣 i 中的標記 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))

貨物運送需求 (例如重量、體積、棧板數量等)。地圖上的鍵必須是說明對應負載類型的 ID (最好同時包含單位)。例如：「weight_kg"、"volume_gallons"、"pallet_count」等。如果特定鍵沒有出現在地圖中，則相對應的載入會被視為空值。

這個物件中包含 "key": value 組合的清單，例如：{ "name": "wrench", "mass": "1.3kg", "count": "3" }.
allowedVehicleIndices[]

integer

可能提供運送作業的一組車輛。如果空白，所有車輛都可以執行這項動作。車輛是按照 ShipmentModel 的 vehicles 清單中的索引指定。
costsPerVehicle[]

number

指定每輛車出貨時產生的費用。如有指定，則必須具備以下條件：

  • 元素數量與 costsPerVehicleIndices 相同。costsPerVehicle[i] 對應至型號的車輛 costsPerVehicleIndices[i]。
  • 元素數量就和模型中車輛的數量相同i-th 元素對應至模型的車輛 #i。

這些費用必須與 penaltyCost 相同，且不得為負數。如果沒有這類費用，請將這個欄位留空。
costsPerVehicleIndices[]

integer

costsPerVehicle 適用的車輛索引。如果不是空白，就必須有與 costsPerVehicle 相同的元素數量。車輛索引只能指定一次。如果從 costsPerVehicleIndices 中排除某輛車，則費用為零。
pickupToDeliveryAbsoluteDetourLimit

string (Duration format)

指定相較於從上車到到貨的最短路徑，指定絕對差道時間。指定的值必須為正數，且運送資訊必須至少包含自取和外送。

舉例來說，對於從所選取貨替代選項直接前往指定配送替代地址的時間，請耐心等候。然後設定 pickupToDeliveryAbsoluteDetourLimit 就會強制執行：

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

如果在同一批貨物上同時指定相對和絕對限制，則每組可能的自取/外送組合會使用較多限制。自 2017 年 10 月起，只有在未以車輛屬性為依據的行程期間，系統才會支援改道活動。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
pickupToDeliveryTimeLimit

string (Duration format)

指定從開始取貨到開始出貨的最長時間。指定的值必須為正數，且運送資訊必須至少包含自取和外送。這不受取貨和外送選取的替代品項，或車輛速度而定。這可以同時指定最大轉乘限制條件：解決方案會同時遵循兩個規格。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「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

指定從上車到下車的最短路徑，比較最長的相對往返時間。指定的值必須為正數，且運送資訊必須至少包含自取和外送。

舉例來說，對於從所選取貨替代選項直接前往指定配送替代地址的時間，請耐心等候。然後設定 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)。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「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 的標籤。這個標籤會在回應中回報為 visitLabel，在對應的 ShipmentRoute.Visit 中。

LatLng

代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定，否則這個物件必須符合 WGS84 標準。此外，值必須在正規化範圍內。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數，必須介於 [-90.0, +90.0] 的範圍之間。
longitude

number

經度度數，必須介於 [-180.0, +180.0] 的範圍之間。

途經點

封裝路線點。路線控點會標出 VisitRequests 的抵達和出發地點，以及車輛的起點和終點。

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

選用設定。表示這個路線控點的位置為優先於車輛在特定道路上停下。設定這個值後，路線就會通過該位置，這樣一來，車輛就會在該位置偏離道路中心的一側停靠。這個選項不適用於「WALKING」交通模式。
聯集欄位 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 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
endTime

string (Timestamp format)

硬性時間範圍的結束時間。如未指定，系統會將該值設為 ShipmentModel.global_end_time。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
softStartTime

string (Timestamp format)

時間範圍的軟開始時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
softEndTime

string (Timestamp format)

時間範圍的軟結束時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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))

車輛容量 (例如重量、體積、棧板數量)。地圖上的鍵是載入類型的 ID，與 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))

指定從 VisitTypes 字串到時間長度的對應。時間長度除了 VisitRequest.duration，用來在造訪指定 visitTypes 時消耗的時間。如果指定 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 地圖平台路線優先 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。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
softMaxDuration

string (Duration format)

軟性限制不會強制執行持續時間上限，但如果違反，則會導致路線產生費用。這筆費用會併入模型中定義的其他費用，而單位也相同。

如已定義，softMaxDuration 不得為負數。如果同時定義了 maxDuration，則 softMaxDuration 必須小於 maxDuration。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
quadraticSoftMaxDuration

string (Duration format)

軟性限制不會強制執行持續時間上限，但如果違反，會導致路徑在期間產生二次級費用。這筆費用會併入模型中定義的其他費用，而單位也相同。

如已定義，quadraticSoftMaxDuration 不得為負數。如果也定義了 maxDuration，則 quadraticSoftMaxDuration 必須小於 maxDuration，且差額不得超過一天：

maxDuration - quadraticSoftMaxDuration <= 86400 seconds

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「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)

嚴格限制會限制距離不超過 maxMeters。限制不得為負數。
softMaxMeters

string (int64 format)

非強制性的距離上限不會強制執行距離上限，但當用量超出上限時，其費用會加計到模型中定義的其他費用，也就是相同的單位。

如果已定義的 softMaxMeters 必須小於 maxMeters，且不得為負數。
costPerKilometerAboveSoftMax

number

如果距離超過 softMaxMeters 的上限，每公里產生的費用。如果距離未達限制，額外費用則為 0。如果距離未超過限制，則使用計算費用的公式如下：

  (distanceMeters - softMaxMeters) / 1000.0 *
  costPerKilometerAboveSoftMax.

費用不得為負數。

BreakRule

產生車輛休息時間 (例如午休時間) 的規則。「休息時間」是指車輛在目前位置保持閒置狀態且無法進行任何造訪的連續時間範圍。可能會發生下列狀況：

  • 在兩次造訪間來回移動的期間 (包括造訪前後的等待時間，但不在造訪中途)，此時，您便可延長訪客兩次造訪之間的相應運送時間。
  • 或車輛開始之前 (車輛不得在休息中開始)，這樣就不會影響車輛的開始時間。
  • 或車輛結束後 (Ditto，車輛結束時間)。
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 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
latestStartTime

string (Timestamp format)

必要欄位。廣告插播的開頭上限 (含)。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
minDuration

string (Duration format)

必要欄位。廣告插播的時間長度下限。必須為正數。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。

FrequencyConstraint

您可以強制執行最短廣告插播頻率，藉此進一步限制上述廣告插播的頻率和時間長度，例如「每 12 小時必須休息至少 1 小時」。假設這個結果可以解讀為「在 12 小時的任何滑動時間範圍內，至少要有一個間隔至少一小時」，則範例會轉譯為下列 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 的說明。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
maxInterBreakDuration

string (Duration format)

必要欄位。路線中任何時間間隔的最長間隔時間 (不包含至少一部分的duration >= minBreakDuration間隔)。必須為正數。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「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 數量相同。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「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)

指定執行這項轉場效果時發生的延遲時間。

這類延遲一律會在來源造訪完成「之後」以及開始目的地造訪「之前」，

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。

ShipmentTypeIncompatibility

根據 shippingType 指定貨件之間的不相容問題。根據不相容模式，同一條路線上出現不相容的貨運情況也會受到限制。

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

根據出貨類型指定不同貨件的運輸需求。要求細節由需求模式定義。

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 取貨」。

此外，優先順序只會在這兩件出貨時套用，否則會遭到忽略。

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

boolean

指出「第一個」事件是否為提交事件。
secondIsDelivery

boolean

表示「second」事件是否為提交。
offsetDuration

string (Duration format)

「第一個」和「秒」事件之間的偏移值。可以是負數。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。
firstIndex

integer

「第一個」事件的運送索引。必須指定這個欄位。
secondIndex

integer

「第二件」事件的出貨索引。必須指定這個欄位。