Method: projects.optimizeTours

傳送包含 ShipmentModel 的 OptimizeToursRequest，並傳回包含 ShipmentRoute 的 OptimizeToursResponse，這些是車輛執行的一系列路線，可將整體成本降至最低。

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

目標是將 ShipmentRoute 指派給 Vehicle，以盡可能降低總成本，其中成本包含 ShipmentModel 中定義的多個元件。

HTTP 要求

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*}: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必須位於指定範圍內，且不能複製。
  • 對於所有造訪，shipmentIndex 和 visitRequestIndex 都必須在範圍內。
  • 一筆出貨只能參照一條路徑。
  • 取貨/送貨運送服務的取貨作業必須在送貨前完成。
  • 每筆訂單只能使用一種取貨或送貨替代方案。
  • 而且時間都會增加 (例如vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime)。
  • 您只能在允許的車輛上進行出貨。如果 Shipment.allowed_vehicle_indices 為空白，或其 vehicleIndex 包含在 Shipment.allowed_vehicle_indices 中，系統就會允許該車輛。
  • 如果將 avoidUTurns 設為 true，則必須為相關造訪設定 injectedSolutionLocationToken

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

object (InjectedSolutionConstraint)

限制最佳化演算法，以找出類似於先前解決方案的最終解決方案。例如，此標記可用於凍結已完成或完成但不能修改的路徑部分。

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

object (ShipmentRoute)

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

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

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

這個欄位不得與 injectedFirstSolutionRoutes 或 injectedSolutionConstraint 搭配使用。

Shipment.ignore 和 Vehicle.ignore 對行為沒有任何影響。無論是否忽略相關的貨運或車輛，所有非空白路線的造訪點之間，仍會填入折線。
interpretInjectedSolutionsUsingLabels

boolean

如果是 true：

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

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

如果插入的解決方案中的 vehicleLabel 不對應至要求車輛，系統會從解決方案中移除對應的路線，並一併移除其造訪次數。如果插入的解決方案中的 shipmentLabel 與要求傳送作業不符，系統會從解決方案中移除對應的造訪。如果注入的解決方案中的 SkippedShipment.label 與要求的傳送作業不符，系統會從解決方案中移除 SkippedShipment。

從已插入的解決方案中移除路徑瀏覽或整個路徑，可能會影響隱含限制，進而導致解決方案變更、驗證錯誤或無法執行。

注意：呼叫端必須確保每個 Vehicle.label (resp. Shipment.label) 會在兩個相關要求中，明確指出所使用的車輛 (或相應的出貨) 實體：產生用於注入解決方案的 OptimizeToursResponse 的過去要求，以及包含注入解決方案的目前要求。上述的唯一性檢查無法保證符合這項規定。
considerRoadTraffic

boolean

在計算 ShipmentRoute 欄位 Transition.travel_duration、Visit.start_time 和 vehicleEndTime 時，將流量估算納入考量；設定 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

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

回應主體

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

授權範圍

需要下列 OAuth 範圍：

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

身分與存取權管理權限

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

  • routeoptimization.locations.use

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