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

Method: projects.locations.optimizeTours

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

傳送包含 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` 為空白，或其 `vehicleIndex` 包含在 `Shipment.allowed_vehicle_indices` 中，系統就會允許該車輛。如果注入的解決方案不可行，系統不一定會傳回驗證錯誤，而是可能傳回表示不可行性的錯誤。
`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` 欄位。當建立解決方案後，要求中的運送或車輛索引發生變更時，即可使用這項方法。這可能是因為運送或車輛已從要求中移除或新增。如果為 true，則下列類別中的標籤在該類別中最多只能出現一次：要求中的 `Vehicle.label`；要求中的 `Shipment.label`； `ShipmentRoute.vehicle_label` 在注射溶液中；插入的解決方案中的 `SkippedShipment.label` 和 `ShipmentRoute.Visit.shipment_label` (除了接送/送達訪問組合，其 `shipmentLabel` 必須出現兩次)。如果插入的解決方案中的 `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

詳情請參閱 IAM 說明文件。