Method: projects.locations.optimizeTours

傳送包含 ShipmentModelOptimizeToursRequest,並傳回內含 ShipmentRouteOptimizeToursResponse,也就是車輛將總成本降至最低的一組路線。

ShipmentModel 模型主要包含需要執行的 Shipment,以及用於傳輸 ShipmentVehicleShipmentRoute 會將 Shipment 指派給 Vehicle。具體來說,系統會為每輛車輛指派一系列 Visit,其中 Visit 對應至 VisitRequest,也就是 Shipment 的接送或送達地點。

目標是將 ShipmentRoute 指派給 Vehicle,藉此盡可能降低 ShipmentModel 中定義多個元件的總費用。

HTTP 要求

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*/locations/*}:optimizeTours

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
parent

string

必要欄位。指定專案或位置即可撥打電話。

格式:* projects/{project-id} * projects/{project-id}/locations/{location-id}

如未指定位置,系統會自動選擇區域。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
欄位
timeout

string (Duration format)

如果設定了逾時,伺服器會在逾時期限或同步要求的伺服器期限已過 (以較早者為準) 之前傳回回應。

如果是非同步要求,伺服器會在逾時屆滿前 (如有) 產生解決方案。

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

model

object (ShipmentModel)

要解決的運送模型。

solvingMode

enum (SolvingMode)

根據預設,解析模式為 DEFAULT_SOLVE (0)。

searchMode

enum (SearchMode)

用於解決要求的搜尋模式。

injectedFirstSolutionRoutes[]

object (ShipmentRoute)

引導最佳化演算法尋找與先前解決方案相似的第一個解決方案。

建構第一個解決方案時,模型會受到限制。在第一個解決方案中,凡是未在路線上執行的運送作業都會隱含略過,但可能會在後續解決方案中執行。

解決方案必須滿足一些基本的有效性假設:

  • 對於所有路徑,vehicleIndex必須位於指定範圍內,且不能複製。
  • 所有造訪的 shipmentIndexvisitRequestIndex 都必須在範圍內。
  • 一筆出貨只能參照一條路徑。
  • 取貨服務配送完成後,請務必安排取貨服務配送訂單。
  • 同一運送的貨品只能有一個取貨替代服務或送貨方式。
  • 對於所有路線,時間都會增加 (也就是vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime)。
  • 您只能在允許的車輛上進行出貨。如果 Shipment.allowed_vehicle_indices 為空,或 Shipment.allowed_vehicle_indices 包含車輛的 vehicleIndex,則允許刊登車輛。

如果插入的解決方案不可行,則不一定會傳回驗證錯誤,系統可能會改為傳回不可行的錯誤。

injectedSolutionConstraint

object (InjectedSolutionConstraint)

限制最佳化演算法,找出類似先前的解決方案的最終解決方案。舉例來說,您可以使用此方法,將已完成或將要完成但不得修改的路線部分凍結。

如果插入的解決方案不可行,則不一定會傳回驗證錯誤,系統可能會改為傳回不可行的錯誤。

refreshDetailsRoutes[]

object (ShipmentRoute)

如果留空,系統就會重新整理指定路線,而不會修改行程的基礎造訪順序或交通時間:系統只會更新其他詳細資訊。這麼做無法解決模型問題,

截至 2020 年 11 月,這個方法只會填入非空路線的多邊形,且需要 populatePolylines 為 true。

傳入路徑的 routePolyline 欄位可能與路徑 transitions 不一致。

這個欄位不得與 injectedFirstSolutionRoutesinjectedSolutionConstraint 搭配使用。

Shipment.ignoreVehicle.ignore 對行為沒有任何影響。無論是否忽略相關的運送或車輛,系統仍會在所有非空白路線的所有造訪之間填入折線。

interpretInjectedSolutionsUsingLabels

boolean

如果為 true:

這項解釋適用於 injectedFirstSolutionRoutesinjectedSolutionConstraintrefreshDetailsRoutes 欄位。如果要求中的運送或車輛索引在解決方案建立後有所變更,可以使用這項屬性,可能是因為運輸或車輛從要求中移除或新增至要求中。

如為 true,下列類別中的標籤最多只能出現一次:

如果插入的解決方案中的 vehicleLabel 不符合要求車輛,系統會將對應的路線和造訪資料從解決方案中移除。如果插入解決方案中的 shipmentLabel 不符合要求運送要求,系統會將相應的造訪動作從解決方案中移除。如果插入解決方案中的 SkippedShipment.label 不符合要求運送要求,系統會將 SkippedShipment 從解決方案中移除。

從插入解決方案中移除路徑造訪或整條路線,可能會影響隱含的限制,進而影響解決方案、驗證錯誤或無法運作。

注意:呼叫端必須確保每個 Vehicle.label (因應Shipment.label) 可明確識別兩個相關要求中使用的車輛 (彈性運送) 實體:過去產生插入解決方案所用 OptimizeToursResponse 的要求,以及目前包含插入解決方案的要求。上述獨特性檢查不足以保證這項規定。

considerRoadTraffic

boolean

計算 ShipmentRoute 欄位 Transition.travel_durationVisit.start_timevehicleEndTime 時,請將流量估算納入考量;設定 ShipmentRoute.has_traffic_infeasibilities 欄位,以及計算 OptimizeToursResponse.total_cost 欄位。

populatePolylines

boolean

如果為 true,則會在回應 ShipmentRoute 中填入折線。

populateTransitionPolylines

boolean

如果為 true,則會在回應 ShipmentRoute.transitions 中填入折線。

allowLargeDeadlineDespiteInterruptionRisk

boolean

如果設定了這個項目,該要求的期限 (請參閱 https://grpc.io/blog/deadlines) 最多可以有 60 分鐘。否則,最長期限僅為 30 分鐘。請注意,長時間的要求具有極大 (但仍然很小) 的干擾風險。

useGeodesicDistances

boolean

如果設為 true,系統會使用測地線距離 (而非 Google 地圖距離) 計算移動距離,並使用 geodesicMetersPerSecond 定義的測速距離以測地線距離計算行程時間。

label

string

可能會用來識別這項要求的標籤,並回報於 OptimizeToursResponse.request_label 中。

geodesicMetersPerSecond

number

如果 useGeodesicDistances 為 true,就必須設定這個欄位,並定義計算交通時間時要套用的速度。這個值必須至少為 1.0 公尺/秒。

maxValidationErrors

integer

截斷傳回的驗證錯誤數量。這些錯誤通常會以 BadRequest 錯誤詳細資料的形式附加至 INVALID_src 錯誤酬載 (https://cloud.google.com/apis/design/errors#error_details),除非 ResolutionMode=VALIDATE_ONLY:請參閱 OptimizeToursResponse.validation_errors 欄位。預設值為 100,上限是 10,000。

回應主體

如果成功,回應主體會包含 OptimizeToursResponse 的執行例項。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/cloud-platform

身分與存取權管理權限

必須具備 parent 資源的下列 IAM 權限:

  • routeoptimization.locations.use

詳情請參閱身分與存取權管理說明文件