本頁面由 Cloud Translation API 翻譯而成。

Method: projects.locations.optimizeTours

HTTP 要求
路徑參數
要求主體
- JSON 表示法
回應主體
授權範圍

傳送包含 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/*/locations/*}:optimizeTours

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

路徑參數

參數

參數
`parent`	`string` 必要欄位。目標專案或位置即可進行通話。格式：* `projects/{project-id}` * `projects/{project-id}/locations/{location-id}` 如未指定位置，系統會自動選擇區域。

parent

string

必要欄位。目標專案或位置即可進行通話。

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

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

要求主體

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

JSON 表示法

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,
  "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` 為空，或 `Shipment.allowed_vehicle_indices` 中包含車輛的 `vehicleIndex`，就可以允許車輛。如果插入的解決方案無法運作，系統不一定會傳回驗證錯誤，且可能會改為傳回不可行的錯誤。
`injectedSolutionConstraint`	`object (InjectedSolutionConstraint)` 限制最佳化演算法，找出與先前解決方案類似的最終解決方案。舉例來說，這個引數可用來凍結部分已完成或即將完成但不能修改的路線。如果插入的解決方案無法運作，系統不一定會傳回驗證錯誤，且可能會改為傳回不可行的錯誤。
`refreshDetailsRoutes[]`	`object (ShipmentRoute)` 如果不是空白，指定路線就會重新整理，而不會修改其基礎的造訪順序或交通時間：僅會更新其他詳細資訊。這無法解決模型的問題。自 2020 年 11 月起，這項操作只會填入非空白路線的折線，而且需要 `populatePolylines` 為 true。傳入路徑的 `routePolyline` 欄位可能會與路徑 `transitions` 不一致。這個欄位不得與 `injectedFirstSolutionRoutes` 或 `injectedSolutionConstraint` 搭配使用。 `Shipment.ignore` 和 `Vehicle.ignore` 對行為沒有影響。在所有非空白路線的所有造訪之間，仍會填入折線，無論相關運送或車輛是否予以忽略。
`interpretInjectedSolutionsUsingLabels`	`boolean` 如為 true：使用 `ShipmentRoute.vehicle_label` 而不是 `vehicleIndex`，比對插入解決方案中的路線與要求中的車輛；如果非空白，重複使用原始 `ShipmentRoute.vehicle_index` 對應至新的 `ShipmentRoute.vehicle_index` 以更新 `ConstraintRelaxation.vehicle_indices`，但對應關係必須明確 (也就是說，多個 `ShipmentRoute` 不得共用相同的原始 `vehicleIndex`)。使用 `ShipmentRoute.Visit.shipment_label` 而不是 `shipmentIndex`，比對插入解決方案中的造訪記錄與要求中的出貨；使用 `SkippedShipment.label` 而不是 `SkippedShipment.index`，比對插入解決方案中略過的運送與要求出貨。此解釋適用於 `injectedFirstSolutionRoutes`、`injectedSolutionConstraint` 和 `refreshDetailsRoutes` 欄位。如果要求中的貨物或車輛索引在解決方案建立後有所變更，就可使用這個屬性，或許是因為貨物或車輛已從要求中移除或新增。如果設為「是」，以下類別的標籤最多只能出現一次：要求中的 `Vehicle.label`；要求中的 `Shipment.label`； `ShipmentRoute.vehicle_label`；在插入的解決方案中；在已插入的解決方案中納入 `SkippedShipment.label` 和 `ShipmentRoute.Visit.shipment_label` (取貨/外送造訪組合除外，其 `shipmentLabel` 必須出現兩次)。如果插入解決方案中的 `vehicleLabel` 與要求車輛不符，系統就會將對應的路徑和相關路徑一併從解決方案中移除。如果插入解決方案中的 `shipmentLabel` 與要求運送不符，則會從解決方案中移除對應的造訪。如果插入解決方案中的 `SkippedShipment.label` 與要求運送不符，就會從解決方案中移除 `SkippedShipment`。從插入的解決方案中移除路線造訪記錄或整個路徑可能會對隱含的限制產生影響，進而導致解決方案改變、驗證錯誤或無法發揮作用。注意：呼叫端必須確保每個 `Vehicle.label` (回應。`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` 如果設定了這個值，該要求便會有最多 60 分鐘的期限 (請參閱 https://grpc.io/blog/deadlines)。否則，期限最長只有 30 分鐘。請注意，長期要求會大幅提高 (但仍然很少) 中斷風險。
`useGeodesicDistances`	`boolean` 如果為 true，系統會使用測地距離 (而非 Google 地圖距離) 計算移動距離，並使用測地線距離 (由 `geodesicMetersPerSecond` 定義的速度) 計算行程時間。
`label`	`string` 可用來識別這項要求的標籤，並回報至 `OptimizeToursResponse.request_label`。
`geodesicMetersPerSecond`	`number` 如果 `useGeodesicDistances` 為 true，就必須設定這個欄位，並定義要用於計算交通時間的速度。其值必須至少為每秒 1.0 公尺。
`maxValidationErrors`	`integer` 縮短傳回的驗證錯誤數量。除非 solvingMode=VALIDATE_ONLY：查看 `OptimizeToursResponse.validation_errors` 欄位，否則這類錯誤通常會以 BadRequest 錯誤詳細資料的形式附加在 INVALID_並進行錯誤酬載 (https://cloud.google.com/apis/design/errors#error_details)。預設值為 100，上限為 10,000。

回應主體

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

授權範圍

需要下列 OAuth 範圍：

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