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 (世界標準時間) 將預設為 0，nanos: 0。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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) 會在矩陣 i 中，定義從代碼 durationDistanceMatrixSrcTags(j) 到其他造訪地點的持續時間和距離。

標記會對應至 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))

貨物負載 (例如重量、體積、棧板數量等)。圖中的鍵應為用來說明對應負載類型的 ID，最好也包含單位。例如：「weight_kg」、「volume_gallons」、「pallet_count」等。如果指定鍵未顯示在地圖上，則相應的載入項目會視為空值。

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

integer

可能提供這項運送作業的車輛組合。如果留空，所有車輛都可以執行這項作業。車輛會以 ShipmentModel 的 vehicles 清單中的索引提供。
costsPerVehicle[]

number

指定每輛車出貨時的運費。指定的變數必須包含 EITHER：

  • 等同 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 月 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 月 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」的標籤。在回覆中，這個標籤會在對應的 ShipmentRoute.Visit 中回報為 visitLabel。

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」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
endTime

string (Timestamp format)

硬性時間範圍結束時間。如果未指定，則會設為 ShipmentModel.global_end_time。

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

string (Timestamp format)

時間範圍的正規開始時間。

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

string (Timestamp format)

時間範圍的虛假結束時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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 字串到 times 的對應。時間長度除了 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)

硬性限制會將距離限制在 maxMeter 內。限制值不得為負數。
softMaxMeters

string (int64 format)

非強制規定的距離上限並未強制執行，不過一旦違反，成本就會加起來，等於模型中定義的其他費用，且單位相同。

如果定義的 softMaxMeters 必須小於 maxMeters，且不得為負數。
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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
latestStartTime

string (Timestamp format)

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

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

根據出貨類型，指定不同運送方式間的不相容問題。系統會依據不相容模式，限制同一條路線上不相容的運送方式。

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已開始。

不過，有些優先順序可代表相同 (或相關) 事件，例如：「商品到貨後取貨」和「C 從 取件 B 發生時取貨」。

此外，只有在兩項運送作業都發生時，優先順序才會套用，其他作業則遭到忽略。

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

boolean

表示是否為「第一個」就是一項外送服務
secondIsDelivery

boolean

表示是否為「秒」就是一項外送服務
offsetDuration

string (Duration format)

「第一個」值之間的偏移和「second」活動。可以是負值。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
firstIndex

integer

「第一個」的運送索引活動。必須指定此欄位。
secondIndex

integer

「第二」的運送索引活動。必須指定此欄位。