Package google.maps.routeoptimization.v1

索引

RouteOptimization

這項服務可最佳化車輛導覽。

特定類型欄位的有效性：

  • google.protobuf.Timestamp
    • 時間採用 Unix 時間格式，也就是自 1970 年 1 月 1 日 00:00:00 (UTC) 起算的秒數。
    • 秒數必須介於 [0, 253402300799]，也就是 [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00]。
    • nanos 必須未設定或設為 0。
  • google.protobuf.Duration
    • 秒數必須介於 [0, 253402300799]，也就是 [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00]。
    • nanos 必須未設定或設為 0。
  • google.type.LatLng
    • 緯度必須介於 [-90.0, 90.0] 之間。
    • 經度必須介於 [-180.0, 180.0] 之間。
    • 至少一個經緯度不得為零。
BatchOptimizeTours

rpc BatchOptimizeTours(BatchOptimizeToursRequest) returns (Operation)

以批次形式，為一或多則 OptimizeToursRequest 訊息最佳化車輛行程。

這個方法是長時間執行的作業 (LRO)。最佳化輸入內容 (OptimizeToursRequest 訊息) 和輸出內容 (OptimizeToursResponse 訊息) 會以使用者指定的格式，從 Cloud Storage 讀取及寫入。與 OptimizeTours 方法類似，每個 OptimizeToursRequest 都包含 ShipmentModel，並傳回包含 ShipmentRoute 欄位的 OptimizeToursResponse，這些欄位是一組車輛要執行的路線，可將整體成本降到最低。

使用者可以輪詢 operations.get 來查看 LRO 的狀態：

如果 LRO done 欄位為 false，表示至少有一項要求仍在處理中。其他要求可能已順利完成，結果會儲存在 Cloud Storage 中。

如果 LRO 的 done 欄位為 true，表示所有要求都已處理完畢。成功處理的要求結果會儲存在 Cloud Storage 中，失敗的要求則不會。如果 LRO 的 error 欄位已設定，則包含其中一個失敗要求產生的錯誤。

授權範圍

需要下列 OAuth 範圍：

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

需要 parent 資源的下列 IAM 權限：

  • routeoptimization.operations.create

詳情請參閱 IAM 說明文件。
OptimizeTours

rpc OptimizeTours(OptimizeToursRequest) returns (OptimizeToursResponse)

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

ShipmentModel 模型主要由需要執行的 Shipment 和可用於運送 Shipment 的 Vehicle 組成。ShipmentRoute 會將 Shipment 指派給 Vehicle。具體來說，系統會為每輛車指派一系列 Visit，其中 Visit 對應至 VisitRequest，也就是 Shipment 的取貨或送貨。

目標是將 ShipmentRoute 指派給 Vehicle，盡量降低總成本，而成本有許多在 ShipmentModel 中定義的元件。

授權範圍

需要下列 OAuth 範圍：

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

需要 parent 資源的下列 IAM 權限：

  • routeoptimization.locations.use

詳情請參閱 IAM 說明文件。
OptimizeToursLongRunning

rpc OptimizeToursLongRunning(OptimizeToursRequest) returns (Operation)

這是 OptimizeTours 方法的變體，專為具有大型逾時值的最佳化作業設計。對於耗時超過幾分鐘的最佳化作業，建議使用這個方法，而非 OptimizeTours 方法。

傳回的 long-running operation (LRO) 名稱格式為 <parent>/operations/<operation_id>，可用於追蹤運算進度。metadata 欄位類型為 OptimizeToursLongRunningMetadata。如果成功，response 欄位類型為 OptimizeToursResponse。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/otlr/make-request。

授權範圍

需要下列 OAuth 範圍：

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

需要 parent 資源的下列 IAM 權限：

  • routeoptimization.operations.create

詳情請參閱 IAM 說明文件。
OptimizeToursUri

rpc OptimizeToursUri(OptimizeToursUriRequest) returns (Operation)

這是 OptimizeToursLongRunning 方法的變體，專為具有大型逾時值和大型輸入/輸出大小的最佳化作業而設計。

用戶端會指定儲存在 Google Cloud Storage 中的 OptimizeToursRequest URI，伺服器則會將 OptimizeToursResponse 寫入用戶端指定的 Google Cloud Storage URI。

如果最佳化作業需要幾分鐘以上的時間，且輸入/輸出大小超過 8 MB，建議使用這個方法，而非 OptimizeTours 方法，但這個方法也適用於較短時間和較小規模的最佳化作業。

傳回的 long-running operation (LRO) 名稱格式為 <parent>/operations/<operation_id>，可用於追蹤運算進度。metadata 欄位類型為 OptimizeToursLongRunningMetadata。如果成功，response 欄位類型為 OptimizeToursUriResponse。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/otlr/make-request。

授權範圍

需要下列 OAuth 範圍：

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

需要 parent 資源的下列 IAM 權限：

  • routeoptimization.operations.create

詳情請參閱 IAM 說明文件。

AggregatedMetrics

所有 Transition 和/或 Visit (所有 ShipmentRoute) 元素的 ShipmentRoute (OptimizeToursResponse) 匯總指標。

欄位
performed_shipment_count

int32

已執行的出貨次數。請注意，取貨和送貨配對只會計算一次。
travel_duration

Duration

路線或解決方案的總旅行時間。
wait_duration

Duration

路線或解決方案的總等待時間。
delay_duration

Duration

路線或解決方案的總延遲時間。
break_duration

Duration

路線或解決方案的休息時間總長度。
visit_duration

Duration

路線或解決方案的總拜訪時間。
total_duration

Duration

總時間長度應等於上述所有時間長度的總和。如果是路線，總時間長度也對應至：

[ShipmentRoute.vehicle_end_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_end_time] - [ShipmentRoute.vehicle_start_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_start_time]
travel_distance_meters

double

路線或解決方案的總移動距離。
max_loads

map<string, VehicleLoad>

整個路線 (或解決方案) 達成的最大負載，針對該路線 (或解決方案) 上的每個數量，計算方式為所有 Transition.vehicle_loads (或 ShipmentRoute.metrics.max_loads。
performed_mandatory_shipment_count

int32

執行的強制出貨次數。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
performed_shipment_penalty_cost_sum

double

已執行貨件的 Shipment.penalty_cost 總和。

實驗性：這個欄位的行為或存在狀態日後可能會變更。

BatchOptimizeToursMetadata

這個類型沒有任何欄位。

BatchOptimizeToursRequest 呼叫的作業中繼資料。

BatchOptimizeToursRequest

要求以非同步作業批次最佳化導覽。每個輸入檔案應包含一個 OptimizeToursRequest，每個輸出檔案則會包含一個 OptimizeToursResponse。要求包含讀取/寫入及剖析檔案的資訊。所有輸入和輸出檔案都應位於同一個專案中。

欄位
parent

string

必填。用於發出呼叫的目標專案和位置。

格式：

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

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

AsyncModelConfig

必填。每個購買模型的輸入/輸出資訊，例如檔案路徑和資料格式。

AsyncModelConfig

用於非同步解決單一最佳化模型的資訊。

欄位
display_name

string

(選用步驟) 使用者定義的模型名稱，可做為別名，方便使用者追蹤模型。
input_config

InputConfig

必填。輸入模型的相關資訊。
output_config

OutputConfig

必填。所需的輸出位置資訊。

BatchOptimizeToursResponse

這個類型沒有任何欄位。

對 BatchOptimizeToursRequest 的回應。作業完成後，系統會在長時間執行作業中傳回這項資訊。

BreakRule

為車輛產生休息時間的規則 (例如午休)。休息是指車輛在目前位置閒置的一段連續時間，期間無法執行任何拜訪。休息時間可能發生在：

  • 兩次造訪之間的行程 (包括造訪前或造訪後的時間，但不包括造訪期間)，在這種情況下，系統會延長兩次造訪之間的相應運送時間，
  • 或在車輛發動前 (車輛可能不會在休息期間發動)，這時就不會影響車輛發動時間。
  • 或車輛結束後 (同樣會顯示車輛結束時間)。
欄位
break_requests[]

BreakRequest

休息時間的順序。請參閱 BreakRequest 訊息。
frequency_constraints[]

FrequencyConstraint

可能適用多個 FrequencyConstraint。這些條件都必須符合這個 BreakRule 的 BreakRequest。請參閱 FrequencyConstraint。

BreakRequest

必須事先瞭解適用於每輛車的休息順序 (即休息次數和順序)。重複的 BreakRequest 會定義該順序，且必須按照該順序發生。休息時間範圍 (earliest_start_time / latest_start_time) 可能會重疊，但必須與順序相容 (系統會檢查)。

欄位
earliest_start_time

Timestamp

必填。休息開始時間的下限 (含)。
latest_start_time

Timestamp

必填。休息開始時間的上限 (含)。
min_duration

Duration

必填。休息時間下限。必須為正數。

FrequencyConstraint

您可進一步限制上述休息的頻率和時間長度，例如強制規定休息頻率下限：「每 12 小時必須休息至少 1 小時」。假設這可解讀為「在任何 12 小時的滑動時間視窗內，必須至少休息 1 小時」，則該範例會轉換為下列 FrequencyConstraint：

{
   min_break_duration { seconds: 3600 }         # 1 hour.
   max_inter_break_duration { 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
欄位
min_break_duration

Duration

必填。這項限制條件的休息時間下限。非負數。請參閱 FrequencyConstraint 的說明。
max_inter_break_duration

Duration

必填。路線中任何時間間隔的允許跨度上限，該間隔至少不包含部分 duration >= min_break_duration 中斷。必須為正數。

DataFormat

輸入和輸出檔案的資料格式。

列舉
DATA_FORMAT_UNSPECIFIED 值無效，格式不得為 UNSPECIFIED。
JSON JavaScript 物件標記法。
PROTO_TEXT 通訊協定緩衝區文字格式。請參閱 https://protobuf.dev/reference/protobuf/textformat-spec/

DistanceLimit

可移動的最大距離限制，可以是硬性或軟性限制。

如果定義了軟性限制，則 soft_max_meters 和 cost_per_kilometer_above_soft_max 都必須定義，且不得為負數。

欄位
max_meters

int64

硬性限制，距離不得超過 max_meters。限制不得為負數。
soft_max_meters

int64

軟性限制不會強制執行距離上限，但如果違反規定，就會產生費用，並以相同單位加總至模型中定義的其他費用。

如果定義 soft_max_meters，則必須小於 max_meters，且不得為負數。
cost_per_kilometer_below_soft_max

double

每公里產生的費用，最高可增加 soft_max_meters，計算公式如下：

  min(distance_meters, soft_max_meters) / 1000.0 *
  cost_per_kilometer_below_soft_max.

route_distance_limit不支援這項費用。
cost_per_kilometer_above_soft_max

double

如果距離超過 soft_max_meters 限制，每公里費用。如果距離低於限制，則額外費用為 0；否則，計算費用的公式如下：

  (distance_meters - soft_max_meters) / 1000.0 *
  cost_per_kilometer_above_soft_max.

費用不得為負值。

GcsDestination

要將輸出檔案寫入哪個 Google Cloud Storage 位置。

欄位
uri

string

必填。Google Cloud Storage URI。

GcsSource

要從中讀取輸入檔案的 Google Cloud Storage 位置。

欄位
uri

string

必填。Google Cloud Storage 物件的 URI，格式為 gs://bucket/path/to/object。

InjectedSolutionConstraint

要求中注入的解決方案，包括必須限制哪些造訪，以及限制方式的相關資訊。

欄位
routes[]

ShipmentRoute

要注入的解決方案路徑。原始解決方案可能會省略部分路線。路線和略過的貨運必須符合 injected_first_solution_routes 列出的基本有效性假設。
skipped_shipments[]

SkippedShipment

要注入的解決方案已略過出貨。部分出貨可能已從原始解決方案中省略。請參閱 routes 欄位。
constraint_relaxations[]

ConstraintRelaxation

針對零或多個車輛群組，指定放寬限制的時間和幅度。如果這個欄位空白，所有非空白的車輛路線都會受到完整限制。

ConstraintRelaxation

針對車輛群組，指定要放寬拜訪次數限制的門檻和程度。skipped_shipment 欄位中列出的貨件會受到限制而跳過，也就是無法執行。

欄位
relaxations[]

Relaxation

所有適用於路線上車輛的拜訪限制放寬條件。vehicle_indices
vehicle_indices[]

int32

指定適用於拜訪限制 relaxations 的車輛索引。如果為空白，則視為預設值，且 relaxations 適用於其他 constraint_relaxations 中未指定的所有車輛。最多只能有一個預設值，也就是最多只能有一個限制寬鬆欄位允許空白 vehicle_indices。即使在多個 constraint_relaxations 中，車輛索引也只能列出一次。

如果 interpret_injected_solutions_using_labels 為 true，則車輛索引的對應方式與 ShipmentRoute.vehicle_index 相同 (請參閱 fields 註解)。

休閒場所

如果 relaxations 為空白，routes 中所有拜訪行程的開始時間和順序都會受到完全限制，且無法在這些路線中插入或新增任何拜訪行程。此外，除非車輛為空 (即沒有任何拜訪行程，且模型中的 used_if_route_is_empty 設為 false)，否則 routes 中車輛的開始和結束時間也會受到完全限制。

relaxations(i).level 指定套用至符合下列條件的造訪 #j 的限制寬鬆程度：

  • route.visits(j).start_time >= relaxations(i).threshold_time 和
  • j + 1 >= relaxations(i).threshold_visit_count

同樣地，如果車輛符合下列條件，車輛啟動時間就會放寬至 relaxations(i).level：

  • vehicle_start_time >= relaxations(i).threshold_time 和
  • relaxations(i).threshold_visit_count == 0，且車輛尾端放寬至 relaxations(i).level，前提是符合下列條件：
  • vehicle_end_time >= relaxations(i).threshold_time 和
  • route.visits_size() + 1 >= relaxations(i).threshold_visit_count

如要套用寬鬆程度，請在造訪次數符合 threshold_visit_count 或 threshold_time 時新增兩個 relaxations，並設定相同的 level，一個只設定 threshold_visit_count，另一個只設定 threshold_time。如果造訪同時符合多個 relaxations 的條件，系統會套用最寬鬆的層級。因此，從車輛出發到依序拜訪路線，再到車輛結束行程，寬鬆程度會越來越寬鬆，也就是說，寬鬆程度不會隨著路線進展而降低。

不符合任何 relaxations 門檻條件的路線拜訪時間和順序會受到完全限制，且無法在這些序列中插入任何拜訪。此外，如果車輛的起點或終點不符合任何放寬條件，時間就會固定，除非車輛是空的。

欄位
level

Level

滿足 threshold_time 和至少 threshold_visit_count 的條件時，適用的限制寬鬆程度。
threshold_time

Timestamp

放寬限制的適用時間，或適用時間之後。level
threshold_visit_count

int32

放寬限制的適用次數下限。如果 threshold_visit_count 為 0 (或未設定)，則 level 可能會直接在車輛啟動時套用。level

如果為 route.visits_size() + 1，level 可能只會套用至車輛終點。如果超過 route.visits_size() + 1，level 就不會套用至該路線。

等級

表示不同的限制寬鬆程度，這些程度會在符合門檻條件時套用至當次和後續的造訪。

下列列舉項目依放寬程度遞增排序。

列舉
LEVEL_UNSPECIFIED

隱含預設寬鬆程度：不放寬任何限制，也就是完全限制所有造訪。

這個值不得明確用於 level。
RELAX_VISIT_TIMES_AFTER_THRESHOLD 造訪開始時間和車輛開始/結束時間會放寬，但每次造訪仍須使用同一輛車，且必須遵守造訪順序，不得在造訪之間或之前插入任何造訪。
RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD 與 RELAX_VISIT_TIMES_AFTER_THRESHOLD 相同，但拜訪順序也會放寬：拜訪只能由這部車輛執行，但可能會變成未執行。
RELAX_ALL_AFTER_THRESHOLD 與 RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD 相同，但車輛也會放寬：在門檻時間或之後的拜訪完全免費，且可能不會執行。

InputConfig

為 [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours] 指定輸入內容。

欄位
data_format

DataFormat

必填。輸入資料格式。
聯集欄位 source。必填。source 只能是下列其中一項：
gcs_source

GcsSource

Google Cloud Storage 位置。這必須是單一物件 (檔案)。

位置

封裝位置 (地理點和選填的航向)。

欄位
lat_lng

LatLng

途中的地理座標。
heading

int32

與車流方向相關聯的羅盤航向。這個值用於指定上車和下車時要使用的道路側。航向值可以介於 0 到 360，其中 0 代表正北方的航向，90 代表正東方的航向，依此類推。

OptimizeToursLongRunningMetadata

這個類型沒有任何欄位。

OptimizeToursLongRunning 呼叫的作業中繼資料。

OptimizeToursRequest

要求提供給導覽最佳化解決工具，定義要解決的貨運模型和最佳化參數。

欄位
parent

string

必填。要發出呼叫的目標專案或位置。

格式：

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

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

Duration

如果設定這個逾時時間，伺服器會在逾時時間經過前或達到同步要求的伺服器期限前傳回回應 (以較早者為準)。

如果是非同步要求，伺服器會在逾時前產生解決方案 (如有可能)。
model

ShipmentModel

要解決的貨運模型。
solving_mode

SolvingMode

根據預設，求解模式為 DEFAULT_SOLVE (0)。
search_mode

SearchMode

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

ShipmentRoute

引導最佳化演算法找出與先前解決方案類似的初始解決方案。

建立第一個解決方案時，模型會受到限制。第一個解決方案會隱含略過未在路線上執行的任何出貨作業，但後續解決方案可能會執行這些作業。

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

  • 所有路線的 vehicle_index 都必須在範圍內，且不得重複。
  • 所有造訪次數的 shipment_index 和 visit_request_index 都必須在範圍內。
  • 一筆貨運只能參照一條路線。
  • 取貨配送貨件的取貨作業必須在配送前完成。
  • 每件貨物只能選擇一種取貨或送貨方式。
  • 所有路線的行車時間都變長 (即vehicle_start_time <= visits[0].start_time <= visits[1].start_time ... <= vehicle_end_time)。
  • 只能在允許的車輛上執行運送作業。如果 Shipment.allowed_vehicle_indices 為空白，或 vehicle_index 包含在 Shipment.allowed_vehicle_indices 中，則允許車輛。

如果注入的解決方案不可行，系統不一定會傳回驗證錯誤，而是可能傳回指出不可行的錯誤。
injected_solution_constraint

InjectedSolutionConstraint

限制最佳化演算法，找出與先前解決方案類似的最終解決方案。舉例來說，這項功能可用於凍結已完成或即將完成但不得修改的部分路線。

如果注入的解決方案不可行，系統不一定會傳回驗證錯誤，而是可能傳回指出不可行的錯誤。
refresh_details_routes[]

ShipmentRoute

如果不是空白，系統會重新整理指定路線，但不會修改基礎的造訪順序或旅行時間，只會更新其他詳細資料。這無法解決模型問題。

自 2020 年 11 月起，這項功能只會填入非空白路線的折線，且必須將 populate_polylines 設為 true。

傳入路線的 route_polyline 欄位可能與路線 transitions 不一致。

這個欄位不得與 injected_first_solution_routes 或 injected_solution_constraint 一併使用。

Shipment.ignore 和 Vehicle.ignore 不會影響行為。無論相關貨件或車輛是否遭到忽略，系統仍會在所有非空白路線的所有拜訪地點之間填入折線。
interpret_injected_solutions_using_labels

bool

如果為 true：

這項解讀適用於 injected_first_solution_routes、injected_solution_constraint 和 refresh_details_routes 欄位。如果要求中的貨運或車輛索引在解決方案建立後有所變更 (可能是因為要求中已移除或新增貨運或車輛)，即可使用這項解讀。

如果是 true，下列類別的標籤在所屬類別中最多只能出現一次：

如果插入解決方案中的 vehicle_label 與要求車輛不符，系統會從解決方案中移除對應路線和拜訪地點。如果注入解決方案中的 shipment_label 與要求出貨不符，系統會從解決方案中移除相應的造訪。如果注入的解決方案中的 SkippedShipment.label 與要求出貨的商品不符，系統會從解決方案中移除 SkippedShipment。

從插入的解決方案中移除路線拜訪或整條路線，可能會影響隱含限制，進而導致解決方案變更、驗證錯誤或不可行。

注意：呼叫者必須確保每個 Vehicle.label (resp. Shipment.label) 可用來不重複地識別車輛 (或貨運) 實體，這兩個相關要求都會用到：產生插入解決方案所用 OptimizeToursResponse 的先前要求，以及包含插入解決方案的目前要求。上述唯一性檢查不足以確保符合這項規定。
consider_road_traffic

bool

計算 ShipmentRoute 欄位 Transition.travel_duration、Visit.start_time 和 vehicle_end_time 時，請將流量估算納入考量；設定 ShipmentRoute.has_traffic_infeasibilities 欄位時，以及計算 OptimizeToursResponse.total_cost 欄位時，也請將流量估算納入考量。
populate_polylines

bool

如為 true，回應 ShipmentRoute 中會填入折線。
populate_transition_polylines

bool

如果是 true，回應 ShipmentRoute.transitions 中會填入折線和路徑權杖。
allow_large_deadline_despite_interruption_risk

bool

如果設定此值，要求最多可有 60 分鐘的期限 (請參閱 https://grpc.io/blog/deadlines)。否則，最長期限僅為 30 分鐘。請注意，長時間執行的要求中斷風險會大幅增加 (但仍很小)。
use_geodesic_distances

bool

如果為 true，系統會使用測地距離 (而非 Google 地圖距離) 計算移動距離，並使用測地距離和 geodesic_meters_per_second 定義的速度計算移動時間。
label

string

可用於識別這項要求的標籤，會回報至 OptimizeToursResponse.request_label。
geodesic_meters_per_second

double

如果 use_geodesic_distances 為 true，則必須設定這個欄位，並定義用於計算行程時間的速度。值不得小於 1.0 公尺/秒。
max_validation_errors

int32

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

SearchMode

定義搜尋行為的模式，在延遲時間與解決方案品質之間取捨。在所有模式中，系統都會強制執行全域要求截止時間。

列舉
SEARCH_MODE_UNSPECIFIED 未指定搜尋模式，等同於 RETURN_FAST。
RETURN_FAST 找到第一個合適的解決方案後，請停止搜尋。
CONSUME_ALL_AVAILABLE_TIME 盡可能花時間尋找更好的解決方案。

SolvingMode

定義求解器應如何處理要求。在 VALIDATE_ONLY 以外的所有模式中，如果要求無效，您會收到 INVALID_REQUEST 錯誤。如要限制傳回的錯誤數量，請參閱 max_validation_errors。

列舉
DEFAULT_SOLVE 解決模型問題。[OptimizeToursResponse.validation_errors][google.cloud.optimization.v1.OptimizeToursResponse.validation_errors] 中可能會發出警告。
VALIDATE_ONLY 只驗證模型，但不求解：盡可能填入最多 OptimizeToursResponse.validation_errors。
DETECT_SOME_INFEASIBLE_SHIPMENTS

只會填入 OptimizeToursResponse.validation_errors 或 OptimizeToursResponse.skipped_shipments，不會實際解決其餘要求 (回應中未設定 status 和 routes)。如果系統偵測到 injected_solution_constraint 路線不可行，就會在 OptimizeToursResponse.validation_errors 欄位中填入相關資訊，並將 OptimizeToursResponse.skipped_shipments 留空。

重要事項：這裡不會傳回所有不可行的出貨，只會傳回在預先處理期間偵測到不可行的出貨。
TRANSFORM_AND_RETURN_REQUEST

只有在 ShipmentModel.objectives 不為空白時，這個模式才有效。要求不會解決，只會驗證並填入與指定目標相應的費用。另請參閱 ShipmentModel.objectives 的文件。產生的要求會以 OptimizeToursResponse.processed_request 形式傳回。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。

OptimizeToursResponse

解決導覽最佳化問題後的回應，其中包含每輛車輛行駛的路徑、已略過的貨物，以及解決方案的整體成本。

欄位
routes[]

ShipmentRoute

為每部車輛計算的路線；第 i 條路線對應模型中的第 i 部車輛。
request_label

string

如果要求中指定標籤，則為 OptimizeToursRequest.label 的副本。
skipped_shipments[]

SkippedShipment

所有已略過的出貨清單。
validation_errors[]

OptimizeToursValidationError

我們獨立偵測到的所有驗證錯誤清單。請參閱 OptimizeToursValidationError 訊息的「MULTIPLE ERRORS」說明。如果 solving_mode 是 DEFAULT_SOLVE，則會包含警告，而非錯誤。
processed_request

OptimizeToursRequest

在某些情況下，我們會先修改傳入的要求，再解決問題 (即新增費用)。如果 solving_mode == TRANSFORM_AND_RETURN_REQUEST，系統會在此處傳回修改過的要求。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。
metrics

Metrics

這項解決方案的時長、距離和用量指標。

指標

所有路線的匯總整體指標。

欄位
aggregated_route_metrics

AggregatedMetrics

匯總路線資料。每個指標都是所有同名 ShipmentRoute.metrics 欄位的總和 (或載入次數上限)。
skipped_mandatory_shipment_count

int32

略過的強制出貨次數。
used_vehicle_count

int32

使用的車輛數量。注意：如果車輛路線為空白且 Vehicle.used_if_route_is_empty 為 true，則車輛視為已使用。
earliest_vehicle_start_time

Timestamp

二手車的最早啟動時間，計算方式為所有二手車的最小值 ShipmentRoute.vehicle_start_time。
latest_vehicle_end_time

Timestamp

二手車的最新結束時間，計算方式為所有二手車的 ShipmentRoute.vehicle_end_time 最大值。
costs

map<string, double>

解決方案的費用，依費用相關要求欄位細分。鍵是相對於輸入 OptimizeToursRequest 的原型路徑，例如「model.shipments.pickups.cost」，值則是對應費用欄位產生的總費用，並彙整整個解決方案。換句話說，costs["model.shipments.pickups.cost"] 是解決方案中所有自取費用的總和。模型中定義的所有費用都會在此詳細列出，但與 TransitionAttributes 相關的費用除外，這類費用自 2022 年 1 月起只會以匯總方式列出。
total_cost

double

解決方案的總費用。費用對應中的所有值總和。

OptimizeToursUriMetadata

這個類型沒有任何欄位。

OptimizeToursUri 呼叫的作業中繼資料。

OptimizeToursUriRequest

OptimizeToursUri 方法使用的要求。

欄位
parent

string

必填。要發出呼叫的目標專案或位置。

格式：

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

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

Uri

必填。包含 OptimizeToursRequest 的 Cloud Storage 物件 URI。
output

Uri

必填。包含 OptimizeToursResponse 的 Cloud Storage 物件 URI。

OptimizeToursUriResponse

OptimizeToursUri 方法傳回的回應。

欄位
output

Uri

(選用步驟) Cloud Storage 物件的 URI，其中包含以 JSON 或 textproto 編碼的 OptimizeToursResponse。如果物件是以 JSON 編碼，物件名稱的副檔名會是 .json。如果物件是以 textproto 編碼，物件名稱的副檔名會是 .txtpb。

資源的 crc32_checksum 可用於驗證資源內容是否經過修改。

OptimizeToursValidationError

說明驗證 OptimizeToursRequest 時發生的錯誤或警告。

欄位
code

int32

驗證錯誤是由一對 (code, display_name) 定義，且一律存在。

這個部分後方的欄位會提供更多錯誤背景資訊。

多項錯誤：如果有多項錯誤，驗證程序會嘗試輸出多項錯誤。就像編譯器一樣，這項程序並不完美。部分驗證錯誤屬於「嚴重」錯誤，會導致整個驗證程序停止。display_name="UNSPECIFIED" 錯誤就屬於這種情況。部分錯誤可能會導致驗證程序略過其他錯誤。

穩定性：code 和 display_name 應非常穩定。但隨著時間推移，可能會出現新的代碼和顯示名稱，導致特定 (無效) 要求產生不同的 (code、display_name) 配對，因為新錯誤隱藏了舊錯誤。例如「MULTIPLE ERRORS」。
display_name

string

錯誤顯示名稱。
fields[]

FieldReference

錯誤情境可能涉及 0 個、1 個 (大部分時間) 或多個欄位。舉例來說，如要參照車輛 #4 和貨運 #2 的首次取貨，可以採取下列做法：

fields { name: "vehicles" index: 4}
fields { name: "shipments" index: 2 sub_field {name: "pickups" index: 0} }

但請注意，特定錯誤碼的基數不應變更。fields
error_message

string

使用者容易理解的錯誤說明字串。code 和 error_message 之間存在 1:1 的對應關係 (當程式碼 !=「UNSPECIFIED」時)。

穩定性：不穩定：與特定 code 相關聯的錯誤訊息可能會隨時間變更 (希望是為了釐清問題)。請改用 display_name 和 code。
offending_values

string

可能包含欄位的值。這項功能不一定適用於所有裝置。請絕對不要依賴這項功能，僅限用於手動模型偵錯。

FieldReference

指定驗證錯誤的脈絡。FieldReference 一律是指這個檔案中的特定欄位，並遵循相同的階層結構。舉例來說，我們可以使用以下程式碼，指定車輛 #5 的元素 #2：start_time_windows

name: "vehicles" index: 5 sub_field { name: "end_time_windows" index: 2 }

不過，我們會省略 OptimizeToursRequest 或 ShipmentModel 等頂層實體，避免訊息過於擁擠。

欄位
name

string

欄位名稱，例如「vehicles」。
sub_field

FieldReference

視需要遞迴巢狀子欄位。

聯集欄位 index_or_key。

index_or_key 只能是下列其中一項：
index

int32

如果欄位重複，則為欄位的索引。
key

string

如果欄位是對應項，則為鍵。

OutputConfig

指定 [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours] 結果的目的地。

欄位
data_format

DataFormat

必填。輸出資料格式。
聯集欄位 destination。必填。destination 只能是下列其中一項：
gcs_destination

GcsDestination

要寫入輸出內容的 Google Cloud Storage 位置。

RouteModifiers

封裝一組選用條件，用於計算車輛路線時。這與 Google Maps Platform Routes Preferred API 中的 RouteModifiers 類似，詳情請參閱：https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteModifiers。

欄位
avoid_tolls

bool

指定是否要盡量避開收費道路。系統會優先選擇不含收費道路的路線。僅適用於機動車輛交通方式。
avoid_highways

bool

指定是否要盡量避開高速公路。系統會優先選擇不含高速公路的路線。僅適用於機動交通方式。
avoid_ferries

bool

指定是否要盡量避開渡輪。系統會優先選擇不含渡輪的路線。僅適用於機動交通方式。
avoid_indoor

bool

(選用步驟) 指定是否應盡量避免室內導航。系統會優先提供不含室內導航的路線。僅適用於「WALKING」旅行模式。

運送地址

單一項目的運送作業，從取貨到送達。如要將運送作業視為已完成，必須有專屬車輛前往其中一個取貨地點 (並相應減少備用容量)，然後前往其中一個送貨地點 (並相應增加備用容量)。

欄位
display_name

string

使用者定義的出貨顯示名稱，長度上限為 63 個字元，可使用 UTF-8 字元。
pickups[]

VisitRequest

與貨件相關聯的一組取貨替代方案。如未指定，車輛只需要前往與送貨地點對應的位置。
deliveries[]

VisitRequest

與出貨相關的一組替代運送方式。如果未指定，車輛只需要前往與取貨地點相應的位置。
load_demands

map<string, Load>

貨運的載重需求 (例如重量、體積、棧板數量等)。地圖中的鍵應為描述相應負載類型的 ID，最好也包含單位。例如：「weight_kg」、「volume_gallons」、「pallet_count」等。如果對應的鍵未顯示在對應表中，系統會將相應的負載視為空值。
allowed_vehicle_indices[]

int32

可能執行這項出貨作業的車輛組合。如果留空，所有車輛都可以執行這項作業。車輛會依據 ShipmentModel's vehicles 清單中的索引提供。
costs_per_vehicle[]

double

指定每輛車輛運送這批貨物時產生的費用。如果指定，則必須符合下列任一條件：

  • 與 costs_per_vehicle_indices 相同數量的元素。costs_per_vehicle[i] 對應於車輛 costs_per_vehicle_indices[i] 的模型。
  • 元素數量與模型中的車輛數量相同。第 i 個元素對應於車輛模型中的第 i 個車輛。

這些費用必須與 penalty_cost 的單位相同，且不得為負值。如果沒有這類費用，請將這個欄位留空。
costs_per_vehicle_indices[]

int32

costs_per_vehicle適用的車輛索引。如果非空白，則必須與 costs_per_vehicle 具有相同數量的元素。車輛索引不得重複指定。如果車輛從 costs_per_vehicle_indices 排除，則其費用為零。
pickup_to_delivery_absolute_detour_limit

Duration

指定與取貨地點到送達地點之間最短路徑相比，絕對繞路時間上限。如要指定，必須為非負值，且貨運必須包含至少一次取貨和一次送達。

舉例來說，假設 t 是從所選取貨替代方案直接前往所選送貨替代方案的最短時間。然後設定 pickup_to_delivery_absolute_detour_limit 強制執行：

start_time(delivery) - start_time(pickup) <=
t + pickup_to_delivery_absolute_detour_limit

如果同一批貨物同時指定相對和絕對限制，系統會針對每個可能的取貨/送貨配對，採用較嚴格的限制。自 2017 年 10 月起，只有在行程時間不取決於車輛時，系統才會支援繞道。
pickup_to_delivery_time_limit

Duration

指定貨件從取貨開始到開始運送之間的最長時長。如要指定，必須為非負值，且貨運必須包含至少一次取貨和一次送達。這與取貨和送貨的替代方案或車輛速度無關。這項限制可以與最大繞道限制一併指定，解決方案會同時遵守這兩項規格。
shipment_type

string

非空白字串，用於指定這批貨的「類型」。這項功能可用於定義 shipment_types 之間的不相容性或需求 (請參閱 ShipmentModel 中的 shipment_type_incompatibilities 和 shipment_type_requirements)。

與單次取貨/送貨的 visit_types 不同：同一批貨的所有取貨/送貨作業都共用相同的 shipment_type。
label

string

指定這批貨件的標籤。這個標籤會在相應 ShipmentRoute.Visit 的 shipment_label 回應中回報。
ignore

bool

如為 True，請略過這批貨，但不要套用 penalty_cost。

如果模型中含有任何 shipment_type_requirements，忽略出貨會導致驗證錯誤。

允許忽略在 injected_first_solution_routes 或 injected_solution_constraint 執行的出貨作業；求解器會從執行路線中移除相關的取貨/送貨行程。系統也會忽略參照忽略出貨作業的 precedence_rules。
penalty_cost

double

如果未完成運送，這筆罰款會加到路線的總成本中。如果系統偵測到其中一個取貨和送貨替代方案，即視為運送完成。費用可採用模型中所有其他費用相關欄位使用的相同單位，且必須為正數。

重要事項：如未指定這項處罰，系統會視為無限期，也就是必須完成出貨。
pickup_to_delivery_relative_detour_limit

double

指定與取貨地點到送達地點之間最短路徑相比，可接受的最大相對繞道時間。如要指定，必須為非負值，且貨運必須包含至少一次取貨和一次送達。

舉例來說，假設 t 是從所選取貨替代方案直接前往所選送貨替代方案的最短時間。然後設定 pickup_to_delivery_relative_detour_limit 強制執行：

start_time(delivery) - start_time(pickup) <=
std::ceil(t * (1.0 + pickup_to_delivery_relative_detour_limit))

如果同一批貨物同時指定相對和絕對限制，系統會針對每個可能的取貨/送貨配對，採用較嚴格的限制。自 2017 年 10 月起，只有在行程時間不取決於車輛時，系統才會支援繞道。

載入

執行拜訪時，如果為取貨，系統可能會在車輛負載中加入預先定義的數量；如果為送貨，則會扣除預先定義的數量。這則訊息會定義這類金額。詳情請參閱《load_demands》。

欄位
amount

int64

執行相應拜訪行程的車輛負重會有所不同。由於這是整數，建議使用者選擇適當的單位，以免失去精確度。必須 ≥ 0。

VisitRequest

要求車輛前往拜訪：車輛有地理位置 (或兩個，詳見下文)、以時間範圍表示的營業時間，以及服務時間長度 (車輛抵達取貨或送貨地點後所花費的時間)。

欄位
arrival_location

LatLng

車輛執行這項 VisitRequest 時抵達的地理位置。如果貨運模型有時間距離矩陣，就不得指定 arrival_location。
arrival_waypoint

Waypoint

車輛執行這項 VisitRequest 時抵達的路線控點。如果貨運模型有時間距離矩陣，則不得指定 arrival_waypoint。
departure_location

LatLng

車輛完成這項 VisitRequest 後的出發地點。如果與 arrival_location 相同，則可省略。如果貨運模型有時間距離矩陣，則不得指定 departure_location。
departure_waypoint

Waypoint

車輛完成這項 VisitRequest 後的出發地點。如果與 arrival_waypoint 相同，則可省略。如果貨運模型有時間距離矩陣，就不得指定 departure_waypoint。
tags[]

string

指定附加至造訪要求的標記。不得使用空白或重複的字串。
time_windows[]

TimeWindow

限制拜訪抵達時間的時間範圍。請注意，車輛可能會在抵達時間範圍外出發，也就是抵達時間 + 預計時間不一定要在時間範圍內。如果車輛在 TimeWindow.start_time 前抵達，可能會導致等待時間。

如果沒有 TimeWindow，表示車輛隨時可以執行這項拜訪。

時段不得重疊或相鄰，且必須遞增排序。

只有在單一時間範圍內，才能設定 cost_per_hour_after_soft_end_time 和 soft_end_time。
duration

Duration

停留時間，也就是車輛抵達和出發之間的時間 (會加到可能的等待時間；請參閱 time_windows)。
cost

double

在車輛路線上處理這項拜訪要求的費用。這項費用可用於支付每次取貨或送貨的替代費用。這項費用的單位必須與 Shipment.penalty_cost 相同，且不得為負值。
load_demands

map<string, Load>

載入這項造訪要求的廣告需求。這與 Shipment.load_demands 欄位類似，但只適用於這個 VisitRequest，而非整個 Shipment。這裡列出的廣告需求會新增至 Shipment.load_demands 列出的廣告需求。
visit_types[]

string

指定拜訪類型。這項資訊可用於分配車輛完成這項行程所需的額外時間 (請參閱 Vehicle.extra_visit_duration_for_visit_type)。

類型只能出現一次。
label

string

指定這個 VisitRequest 的標籤。這個標籤會在相應的 ShipmentRoute.Visit 中，以 visit_label 的形式回報。
avoid_u_turns

bool

指定是否應避免在該位置的行車路線中迴轉。迴轉迴避功能會盡可能避免迴轉，但不保證完全迴避。這項功能仍在實驗階段，行為可能會有所變更。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request。

ShipmentModel

貨運模型包含一組貨運，必須由一組車輛執行，同時盡量降低總成本，也就是下列各項的總和：

  • 車輛路線規劃費用 (所有車輛的總時間費用、行程時間費用和固定費用總和)。
  • 未履行運送義務的罰款。
  • 全球運送時間的成本
欄位
shipments[]

Shipment

模型中必須執行的出貨作業。
vehicles[]

Vehicle

可用於執行拜訪作業的車輛組合。
objectives[]

Objective

這個模型的一組目標，我們會將其轉換為費用。如果不是空白，輸入模型必須免費。如要取得修改後的要求，請使用 solving_mode = TRANSFORM_AND_RETURN_REQUEST。請注意，系統不會解決這類要求。請參閱相關說明文件。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。
global_start_time

Timestamp

模型的全球開始和結束時間：超出這個範圍的時間一律無效。

模型的時間範圍必須少於一年，也就是 global_end_time 和 global_start_time 之間必須相差 31536000 秒。

使用 cost_per_*hour 欄位時，您可能需要將這個時間範圍設為較小間隔，以提升成效 (例如，如果您要模擬單日，就應將全域時間限制設為該日)。如果不設定，系統會使用預設值：世界標準時間 1970 年 1 月 1 日 00:00:00 (即秒數：0，奈秒數：0)。
global_end_time

Timestamp

如未設定，系統會使用 1971 年 1 月 1 日世界標準時間 00:00:00 (即秒數：31536000，奈秒數：0) 做為預設值。
global_duration_cost_per_hour

double

整體計畫的「全球時間長度」是所有車輛最早生效開始時間和最晚生效結束時間的差異。使用者可以為該數量指派每小時成本，盡量縮短作業完成時間。這項成本的單位必須與 Shipment.penalty_cost 相同。
duration_distance_matrices[]

DurationDistanceMatrix

指定模型中使用的時間和距離矩陣。如果這個欄位空白，系統會改用 Google 地圖或測地距離，視 use_geodesic_distances 欄位的值而定。如果這個欄位不空白，use_geodesic_distances 就不能為 true，且 duration_distance_matrix_src_tags 和 duration_distance_matrix_dst_tags 都不能空白。

使用範例：

  • 有兩個地點：locA 和 locB。
  • 1 輛車從 locA 開始路線，並在 locA 結束路線。
  • 在 locB 提出 1 項取貨預約要求。
model {
  vehicles { start_tags: "locA"  end_tags: "locA" }
  shipments { pickups { tags: "locB" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_dst_tags: "locA"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrices {
    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 結束路線，使用「fast」矩陣。
  • 1 輛車從 locB 開始路線，並在 locB 結束路線，使用「slow」矩陣。
  • 1 輛車從 locB 開始路線，並在 locB 結束路線，使用「fast」矩陣。
  • 在 locC 提出 1 項取貨要求。
model {
  vehicles { start_tags: "locA" end_tags: "locB" start_tags: "fast" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "slow" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "fast" }
  shipments { pickups { tags: "locC" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_src_tags: "locC"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrix_dst_tags: "locC"
  duration_distance_matrices {
    vehicle_start_tag: "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
    }
  }
  duration_distance_matrices {
    vehicle_start_tag: "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
    }
  }
}
duration_distance_matrix_src_tags[]

string

定義時間長度和距離矩陣來源的標記；duration_distance_matrices(i).rows(j) 定義從具有標記 duration_distance_matrix_src_tags(j) 的造訪到矩陣 i 中其他造訪的時間長度和距離。

標記會對應至 VisitRequest.tags 或 Vehicle.start_tags。這個欄位中的每個 VisitRequest 或 Vehicle 都必須與一個標記完全相符。請注意，Vehicle 的來源、目的地和矩陣標記可能相同；同樣地，VisitRequest 的來源和目的地標記可能相同。所有標記都必須互不相同，且不得為空字串。如果這個欄位不為空，則 duration_distance_matrices 不得為空。
duration_distance_matrix_dst_tags[]

string

定義時間和距離矩陣目的地的標記；duration_distance_matrices(i).rows(j).durations(k) (分別為 duration_distance_matrices(i).rows(j).meters(k))) 定義從具有標記 duration_distance_matrix_src_tags(j) 的造訪到具有標記 duration_distance_matrix_dst_tags(k) 的造訪，在矩陣 i 中的旅行時間 (分別為距離)。

標記會對應至 VisitRequest.tags 或 Vehicle.start_tags。這個欄位中的每個 VisitRequest 或 Vehicle 都必須與一個標記完全相符。請注意，Vehicle 的來源、目的地和矩陣標記可能相同；同樣地，VisitRequest 的來源和目的地標記可能相同。所有標記都必須互不相同，且不得為空字串。如果這個欄位不為空，則 duration_distance_matrices 不得為空。
transition_attributes[]

TransitionAttributes

新增至模型的轉場效果屬性。
shipment_type_incompatibilities[]

ShipmentTypeIncompatibility

不相容的 shipment_type 組合 (請參閱ShipmentTypeIncompatibility)。
shipment_type_requirements[]

ShipmentTypeRequirement

shipment_type 需求條件集 (請參閱 ShipmentTypeRequirement)。
precedence_rules[]

PrecedenceRule

模型中必須強制執行的優先順序規則集。

重要事項：使用優先順序規則會限制可最佳化問題的大小。如果優先順序規則包含大量出貨內容，系統可能會拒絕要求。
max_active_vehicles

int32

限制有效車輛數量上限。如果車輛的路線至少執行一次出貨作業，該車輛就會處於有效狀態。如果車輛數量多於駕駛人數，且車隊車輛種類不一，這項功能可用於限制路線數量。最佳化功能會選取最適合的車輛子集。必須為嚴格正數。

DurationDistanceMatrix

指定從拜訪地點和車輛起點到拜訪地點和車輛終點的距離和時間矩陣。

欄位
rows[]

Row

指定時間和距離矩陣的資料列。元素數量必須與 ShipmentModel.duration_distance_matrix_src_tags 相同。
vehicle_start_tag

string

標記，用於定義這項時間和距離矩陣適用於哪些車輛。如果留空，則適用於所有車輛，且只能有一個矩陣。

每輛車的起點都必須與一個矩陣完全相符，也就是說，車輛的 start_tags 欄位必須與矩陣的 vehicle_start_tag 欄位完全相符 (且只能與該矩陣相符)。

所有矩陣的 vehicle_start_tag 都必須不同。

資料列

指定時間和距離矩陣的資料列。

欄位
durations[]

Duration

指定資料列的時間長度值。元素數量必須與 ShipmentModel.duration_distance_matrix_dst_tags 相同。
meters[]

double

特定資料列的距離值。如果模型中沒有任何費用或限制參照距離，則可將此欄位留空；否則，此欄位必須與 durations 具有相同數量的元素。

目標

目標會完全取代費用模式，因此與現有費用不相容。每個目標都會對應到預先定義的成本，例如車輛、貨貨運或轉移屬性。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/objectives/make-request。

欄位
type

Type

目標類型。
weight

double

這個目標相對於其他目標的權重。可以是任何非負數，權重總和不必為 1。權重預設為 1.0。

類型

要對應一組費用的目標類型。

列舉
DEFAULT 系統會使用預設費用組合，確保提供合理的解決方案。注意：這項目標可以單獨使用，但如果使用者指定的目標中沒有這項目標，系統一律會以權重 1.0 新增這項目標做為基準。
MIN_DISTANCE 「MIN」目標：盡量縮短總行駛距離。
MIN_WORKING_TIME 盡量縮短所有車輛的總工作時間。
MIN_TRAVEL_TIME 與上述相同，但僅著重於行程時間。
MIN_NUM_VEHICLES 盡量減少使用的車輛數量。

PrecedenceRule

兩個事件 (分別是貨件的取貨或送達) 之間的優先順序規則：「第二個」事件必須在「第一個」事件開始後至少 offset_duration 開始。

多個先後順序可參照相同 (或相關) 事件，例如「B 的取貨時間晚於 A 的送達時間」，以及「C 的取貨時間晚於 B 的取貨時間」。

此外，優先順序只會在兩批貨物都出貨時套用，否則會遭到忽略。

欄位
first_is_delivery

bool

指出「第一個」事件是否為運送。
second_is_delivery

bool

指出「第二個」事件是否為運送。
offset_duration

Duration

「第一個」和「第二個」事件之間的偏移量，可為負值。
first_index

int32

「第一個」事件的出貨索引。這個欄位為必填。
second_index

int32

「第二個」事件的出貨索引。這個欄位為必填。

ShipmentRoute

車輛路線可沿著時間軸分解，如下所示 (假設有 n 次拜訪)：

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

請注意，我們區分以下項目：

  • 「準時事件」，例如車輛的開始和結束時間，以及每次拜訪的開始和結束時間 (即抵達和離開時間)。這些事件會在特定時間發生。
  • 「時間間隔」，例如造訪本身，以及造訪之間的轉換。雖然時間間隔有時可能為零，也就是開始和結束時間相同，但通常會是正數。

不變量：

  • 如有 n 次造訪，就會有 n+1 次轉換。
  • 每次造訪前後都會有轉場效果 (索引相同和索引 + 1)。
  • 車輛啟動後，一律會接著進行轉場 #0。
  • 車輛尾端一律會標示為「轉場 #n」。

放大來看，Transition 和 Visit 的運作方式如下：

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

最後，以下說明如何在轉場期間安排 TRAVEL、BREAKS、DELAY 和 WAIT。

  • 不會重疊。
  • DELAY 是獨一無二的，且必須是下一次造訪 (或車輛結束) 前的連續時間。因此，只要知道延遲時間長度，就能知道延遲的開始和結束時間。
  • 中斷時間是連續且不重疊的時間範圍。回應會指定每個休息時間的開始時間和時長。
  • 「TRAVEL」和「WAIT」是「可搶占」的：在這段轉換期間，這兩者可能會多次中斷。用戶端可以假設「TRAVEL」會「盡快」發生，而「WAIT」會填補剩餘時間。

複雜範例：

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
欄位
vehicle_index

int32

執行路線的車輛，由來源 ShipmentModel 中的索引識別。
vehicle_label

string

執行這條路線的車輛標籤，如果指定，則等於 ShipmentModel.vehicles(vehicle_index).label。
vehicle_start_time

Timestamp

車輛開始行駛路線的時間。
vehicle_end_time

Timestamp

車輛完成路線的時間。
visits[]

Visit

代表路線的造訪順序。visits[i] 是路線中的第 i 次造訪。如果這個欄位空白，表示車輛未使用。
transitions[]

Transition

路徑的轉場效果排序清單。
has_traffic_infeasibilities

bool

如果 OptimizeToursRequest.consider_road_traffic 設為 true，這個欄位表示系統會根據流量估算行程時間，預測路徑時間不一致的情況。在滿足巡訪和車輛時間範圍的同時，可能沒有足夠時間完成交通調整後的行程、延誤和巡訪之間的休息，或是在第一次巡訪前或最後一次巡訪後完成這些事項。例如：

  start_time(previous_visit) + duration(previous_visit) +
  travel_duration(previous_visit, next_visit) > start_time(next_visit)

由於交通狀況導致預估行程時間增加 travel_duration(previous_visit, next_visit)，因此抵達 next_visit 的時間可能會比目前的時間範圍晚。此外，由於預估行程時間增加，以及拜訪或休息時間限制，休息時間可能會被迫與拜訪時間重疊。
route_polyline

EncodedPolyline

路線的編碼折線表示法。只有在 OptimizeToursRequest.populate_polylines 設為 true 時，才會填入這個欄位。
breaks[]

Break

這條路線的車輛排定休息時間。breaks 序列代表時間間隔，每個間隔都從對應的 start_time 開始，持續 duration 秒。
metrics

AggregatedMetrics

這條路線的時長、距離和負重指標。視情況而定，AggregatedMetrics 的欄位會加總所有 ShipmentRoute.transitions 或 ShipmentRoute.visits。
vehicle_fullness

VehicleFullness

VehicleFullness 欄位，計算受限指標與各自車輛限制的接近程度。這些欄位是設有上限的指標欄位 (例如 AggregatedMetrics.travel_distance_meters) 與相關車輛限制 (例如 Vehicle.route_distance_limit) 之間的比例。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
route_costs

map<string, double>

路線費用，依費用相關要求欄位細分。鍵是相對於輸入 OptimizeToursRequest 的 Proto 路徑，例如「model.shipments.pickups.cost」，值則是對應費用欄位產生的總費用，並在整條路線上匯總。換句話說，costs["model.shipments.pickups.cost"] 是路線上所有取貨費用的總和。模型中定義的所有費用都會在此詳細列出，但與 TransitionAttributes 相關的費用除外，這類費用自 2022 年 1 月起只會以匯總方式列出。
route_total_cost

double

路線的總費用，即費用地圖中所有費用的總和。

休息時間

代表中斷執行的資料。

欄位
start_time

Timestamp

休息時間的開始時間。
duration

Duration

休息時間長度。

EncodedPolyline

折線的編碼表示法。如要進一步瞭解折線編碼，請參閱：https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding。

欄位
points

string

代表折線編碼點的字串。

轉移

路徑上兩個事件之間的轉場效果。請參閱 ShipmentRoute 的說明。

如果車輛沒有 start_location 和/或 end_location，對應的行程指標為 0。

欄位
travel_duration

Duration

這段期間的旅行時間。
travel_distance_meters

double

轉場期間的移動距離。
traffic_info_unavailable

bool

透過 OptimizeToursRequest.consider_road_traffic 要求車流量資訊時，如果無法擷取 Transition 的車流量資訊，這個布林值就會設為 true。這可能是暫時性 (即時車流量伺服器發生罕見的故障)，也可能是永久性 (這個位置沒有資料)。
delay_duration

Duration

套用至這項轉換的延遲時間總和。如有延遲，會在下一個事件 (到訪或車輛結束) 發生前 delay_duration 秒開始。查看《TransitionAttributes.delay》。
break_duration

Duration

這段轉場期間內發生的暫停時間總和 (如有)。每個休息時間的開始時間和時長詳細資料會儲存在 ShipmentRoute.breaks 中。
wait_duration

Duration

這段期間的等待時間。等待時間對應的是閒置時間，不包含休息時間。另請注意，這段等待時間可能會分成幾個不連續的時間間隔。
total_duration

Duration

轉移作業的總時間長度 (僅供參考)。這等於：

  • 下次造訪 start_time (或 vehicle_end_time，如果這是最後一次轉換) - 這次轉換的 start_time；
  • 如果 ShipmentRoute.has_traffic_infeasibilities 為 false，則下列項目也成立：`total_duration = travel_duration + delay_duration
  • break_duration + wait_duration`。
start_time

Timestamp

這項轉換作業的開始時間。
route_polyline

EncodedPolyline

遷移期間所遵循路線的編碼折線表示法。只有在 populate_transition_polylines 設為 True 時，才會填入這個欄位。
route_token

string

僅供輸出。不透明權杖，可傳遞至 Navigation SDK，在導航期間重建路線，並在重新規劃路線時，遵守建立路線時的原始意圖。請將這個權杖視為不透明的 Blob。請勿比較不同要求中的值，因為即使服務傳回完全相同的路線，這個值也可能會變更。只有在 populate_transition_polylines 設為 True 時，才會填入這個欄位。
vehicle_loads

map<string, VehicleLoad>

在此轉換期間，車輛的負載量 (適用於出現在這輛車 Vehicle.load_limits 中的每種負載，或在這條路線上進行的某項貨運中，具有非零 Shipment.load_demands 的負載)。

第一次轉移期間的載重是車輛路線的起始載重。然後，每次拜訪後，系統會根據拜訪是取貨還是送貨，在下次轉移的載重中加入或扣除該次拜訪的 load_demands。

VehicleLoad

針對特定類型 (請參閱 Transition.vehicle_loads)，回報車輛在路線上某個時間點的實際負載。

欄位
amount

int64

車輛的負重，以指定類型為準。載入單位通常會以型別表示。詳情請參閱《Transition.vehicle_loads》。

前往

在路線期間進行的拜訪。這項行程對應 Shipment 的取貨或送貨。

欄位
shipment_index

int32

來源 ShipmentModel 中 shipments 欄位的索引。
is_pickup

bool

如果為 true，表示該趟行程是為了取貨 Shipment，否則為送貨。
visit_request_index

int32

Shipment 的取貨或外送欄位索引 (請參閱 is_pickup)。VisitRequest
start_time

Timestamp

開始拜訪的時間。請注意，車輛可能會提早抵達拜訪地點。時間與 ShipmentModel 一致。
load_demands

map<string, Load>

總訪客人數需求，也就是出貨量和訪客人數要求的總和 load_demands。如果造訪是送貨，值會是負數。系統會針對與 Transition.loads 相同的類型回報需求 (請參閱這個欄位)。
detour

Duration

由於造訪地點前已拜訪其他地點，以及時間範圍可能導致等待時間，因此額外繞道時間。如果造訪地點是送貨地點，繞道時間會從對應的取貨地點計算，且等於：

start_time(delivery) - start_time(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

否則，系統會根據車輛 start_location 計算，計算方式如下：

start_time - vehicle_start_time - travel duration from
the vehicle's `start_location` to the visit.
shipment_label

string

如果 Shipment 中有指定，則為對應的 Shipment.label 副本。
visit_label

string

如果 VisitRequest 中有指定，則為對應的 VisitRequest.label 副本。
visit_type

VisitType

(選用步驟) 指定造訪類型。覆寫 Visit.is_pickup 欄位。
injected_solution_location_token

int32

代表造訪地點資訊的不透明權杖。

如果這個造訪的 VisitRequest.avoid_u_turns 設為 true，或請求 OptimizeToursRequest 中的 ShipmentModel.avoid_u_turns 設為 true，則結果路徑的造訪可能會填入這個欄位。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request。

VisitType

指出造訪是取貨、送貨，還是造訪Stop。只有在啟用多模式最佳化時，才會使用造訪Stop。

列舉
VISIT_TYPE_UNSPECIFIED 未指定造訪類型。
PICKUP_SHIPMENT 拜訪次數對應於取貨次數。
DELIVER_SHIPMENT 訪視次數對應至出貨次數。

ShipmentTypeIncompatibility

根據出貨類型，指定出貨項目之間的不相容性。系統會根據不相容模式，限制同一路線上不相容貨件的顯示方式。

欄位
types[]

string

不相容的類型清單。如果清單中的兩批貨件有不同的 shipment_types，即為「不相容」。
incompatibility_mode

IncompatibilityMode

不相容的模式。

IncompatibilityMode

模式：定義同一路線上不相容貨件的外觀限制方式。

列舉
INCOMPATIBILITY_MODE_UNSPECIFIED 未指定不相容模式。請一律不要使用這個值。
NOT_PERFORMED_BY_SAME_VEHICLE 在此模式下，類型不相容的兩批貨物絕不會共用同一輛車。
NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY

在此模式下，類型不相容的兩批貨物絕不會同時出現在同一輛車上：

  • 只有在其中一輛車輛送達後，才能取走另一輛車輛。
  • 如果兩批貨物都只能自取 (無法運送) 或只能運送 (無法自取)，則完全無法共用同一輛車。

ShipmentTypeRequirement

根據出貨類型指定出貨之間的規定。規定的具體內容由規定模式定義。

欄位
required_shipment_type_alternatives[]

string

dependent_shipment_types 要求的替代運送類型清單。
dependent_shipment_types[]

string

dependent_shipment_types 欄位中含有類型的所有貨件，都必須在同一條路線上至少拜訪一個 required_shipment_type_alternatives 類型的貨件。

注意：不得有需求鏈，導致 shipment_type 依附於自身。
requirement_mode

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 與先前相同，但「從屬」貨件必須在運送時，車輛上載有「必要」貨件。

SkippedShipment

指定解決方案中未執行的出貨詳細資料。如果是微不足道的情況，且/或我們能夠找出略過的原因，我們會在此回報原因。

欄位
index

int32

這個索引會對應至來源 ShipmentModel 中的出貨項目索引。
label

string

如果 Shipment 中有指定，則為對應的 Shipment.label 副本。
reasons[]

Reason

說明貨件遭略過原因的清單。請參閱上方的註解 Reason。如果我們無法瞭解貨件遭略過的原因，系統就不會設定原因。
penalty_cost

double

這是 Shipment.penalty_cost 的副本，方便你查看遭略過的出貨項目嚴重程度。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
estimated_incompatible_vehicle_ratio

double

預估無法執行這項出貨作業的車輛比例，原因至少包括下列其中一項。注意：只有在原因與車輛有關時，才會填寫這項資訊。

實驗性：這個欄位的行為或存在狀態日後可能會變更。

原因

如果我們能說明為何跳過出貨，原因會列在這裡。如果所有車輛的原因不盡相同，reason 會有多個元素。略過的貨件不得有重複原因，也就是說，除了 example_vehicle_index 以外，所有欄位都相同。範例：

reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 1
  example_exceeded_capacity_type: "Apples"
}
reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 3
  example_exceeded_capacity_type: "Pears"
}
reasons {
  code: CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT
  example_vehicle_index: 1
}

這批貨物與所有車輛都不相容。原因可能因車輛而異，但至少有一輛車的「蘋果」容量會超出上限 (包括車輛 1)，至少有一輛車的「梨子」容量會超出上限 (包括車輛 3)，且至少有一輛車的距離限制會超出上限 (包括車輛 1)。

欄位
code

Code

請參閱程式碼的註解。
example_vehicle_indices[]

int32

與 example_vehicle_index 相同，但我們提供多個已識別車輛的清單。這份清單不一定詳盡無遺。只有在 [fill_example_vehicle_indices_in_skipped_reasons][] 為 true 時，才會填入這項資訊。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
example_exceeded_capacity_type

string

如果原因代碼為 DEMAND_EXCEEDS_VEHICLE_CAPACITY，請提供超過容量限制的其中一種文件。
example_vehicle_index

int32

如果原因與出貨車輛不相容有關，這個欄位會提供其中一輛相關車輛的索引。

程式碼

識別原因類型的代碼。此處的順序沒有意義。特別是，如果兩種原因都適用，這不會指出解決方案中某個原因是否會出現在另一個原因之前。

列舉
CODE_UNSPECIFIED 請勿使用這個值。
NO_VEHICLE 模型中沒有車輛，因此所有出貨作業都不可行。
DEMAND_EXCEEDS_VEHICLE_CAPACITY 出貨需求超過車輛容量 (部分容量類型)，其中一種是 example_exceeded_capacity_type。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT

執行這項運送作業的必要最短距離 (即從車輛的 start_location 到貨件的取貨和/或送達地點，以及車輛的最終地點) 超過車輛的 route_distance_limit。

請注意，這項計算會使用測地線距離。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT

執行這項運送作業所需的最短時間 (包括行程時間、等待時間和服務時間) 超過車輛的 route_duration_limit。

注意：系統會以最佳情況計算行程時間，也就是測地距離 x 36 公尺/秒 (約 130 公里/小時)。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TRAVEL_DURATION_LIMIT 與上述相同，但我們只比較最短行程時間和車輛的travel_duration_limit。
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TIME_WINDOWS 如果車輛在最早開始時間出發，總時間會導致車輛在最晚結束時間後結束，因此車輛無法在最佳情況下執行這項出貨作業 (請參閱 CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT瞭解時間計算方式)。
VEHICLE_NOT_ALLOWED 出貨商品的 allowed_vehicle_indices 欄位不為空白，且這輛車不屬於該欄位。
VEHICLE_IGNORED

車輛的 ignore 欄位為 true。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
SHIPMENT_IGNORED

出貨商品的 ignore 欄位為 true。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
SKIPPED_IN_INJECTED_SOLUTION_CONSTRAINT

系統已在 injected_solution_constraint中略過這批商品。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
VEHICLE_ROUTE_IS_FULLY_SEQUENCE_CONSTRAINED

injected_solution_constraint 中指定的車輛路線寬鬆條件不允許插入任何拜訪行程。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
ZERO_PENALTY_COST

貨件的違規費用為零。雖然這項功能可做為進階模型選項，但事後也可能說明為何系統略過出貨。

實驗性：這個欄位的行為或存在狀態日後可能會變更。

TimeWindow

時間範圍會限制事件的時間，例如到訪時間，或是車輛的開始和結束時間。

硬性時間範圍界線 start_time 和 end_time 會強制執行事件的最早和最晚時間，因此 start_time <= event_time <= end_time。軟性時間範圍下限 soft_start_time 表示偏好事件發生時間為 soft_start_time 之後，並會根據事件發生時間與 soft_start_time 的時間差，產生相應的費用。軟性時間範圍上限 soft_end_time 表示偏好事件發生時間為 soft_end_time 或之前，但如果事件發生時間晚於 soft_end_time，則會產生與時間成正比的費用。start_time、end_time、soft_start_time 和 soft_end_time 應符合全域時間限制 (請參閱 ShipmentModel.global_start_time 和 ShipmentModel.global_end_time)，並遵守下列規定：

  0 <= `start_time` <= `end_time` and
  0 <= `start_time` <= `soft_start_time` and
  0 <= `soft_end_time` <= `end_time`.
欄位
start_time

Timestamp

硬性時間範圍的開始時間。如果未指定，則會設為 ShipmentModel.global_start_time。
end_time

Timestamp

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

Timestamp

時間範圍的軟性開始時間。
soft_end_time

Timestamp

時段的軟性結束時間。
cost_per_hour_before_soft_start_time

double

如果事件發生時間早於 soft_start_time，則模型中會加入每小時費用，並與其他費用一併計算，計算方式如下：

   max(0, soft_start_time - t.seconds)
                          * cost_per_hour_before_soft_start_time / 3600,
t being the time of the event.

這項費用必須為正數，且只有在設定 soft_start_time 時，才能設定這個欄位。
cost_per_hour_after_soft_end_time

double

如果事件發生在 soft_end_time 之後，模型中會加入每小時費用，計算方式如下：

   max(0, t.seconds - soft_end_time.seconds)
                    * cost_per_hour_after_soft_end_time / 3600,
t being the time of the event.

這項費用必須為正數，且只有在已設定 soft_end_time 時，才能設定這個欄位。

TransitionAttributes

指定路線上連續兩次造訪之間轉換的屬性。同一轉換可套用多個 TransitionAttributes，在這種情況下，所有額外費用都會加總，並套用最嚴格的限制 (遵循自然「AND」語意)。

欄位
src_tag

string

定義這些屬性適用的 (src->dst) 轉換集。

如果來源造訪或車輛啟動的 VisitRequest.tags 或 Vehicle.start_tags 包含 src_tag 或不包含 excluded_src_tag (視這兩個欄位中哪個不為空而定)，則來源造訪或車輛啟動會相符。
excluded_src_tag

string

請參閱 src_tag。src_tag 和 excluded_src_tag 必須恰好有一個不得為空。
dst_tag

string

如果目的地拜訪或車輛結束的 VisitRequest.tags 或 Vehicle.end_tags 包含 dst_tag 或不包含 excluded_dst_tag (視這兩個欄位中哪一個不為空而定)，即為相符。
excluded_dst_tag

string

請參閱 dst_tag。dst_tag 和 excluded_dst_tag 必須恰好有一個不得為空。
cost

double

指定執行這項轉換的費用。這與模型中的所有其他費用採用相同單位，且不得為負數。這項費用會加在所有其他現有費用之上。
cost_per_kilometer

double

指定在執行這項轉換時，每公里行駛距離適用的成本。最多可為車輛新增任何Vehicle.cost_per_kilometer。
distance_limit

DistanceLimit

指定執行這項轉場效果時的行駛距離限制。

自 2021 年 6 月起，系統僅支援軟性限制。
delay

Duration

指定執行這項轉換時發生的延遲。

這項延遲一律發生在完成來源造訪後，以及開始目的地造訪前。

URI

通用資源 ID，指向可由 Route Optimization API 讀取及寫入的資源。

欄位
uri

string

資源的 URI。資源可能尚未存在。

資源內容會編碼為 JSON 或 textproto。系統僅支援 Google Cloud Storage 資源。如果資源編碼為 JSON，資源名稱結尾必須加上 .json。如果資源編碼為 textproto，資源名稱結尾必須加上 .txtpb。舉例來說，JSON 編碼檔案的 Google Cloud Storage URI 可能如下所示：gs://bucket/path/input/object.json。

車輛

此模型代表運送問題中的車輛。解決運送問題時，系統會為這輛車輛建構從 start_location 開始到 end_location 結束的路徑。路徑是一連串的拜訪地點 (請參閱 ShipmentRoute)。

欄位
display_name

string

車輛的自訂顯示名稱，長度上限為 63 個字元，可使用 UTF-8 字元。
travel_mode

TravelMode

旅行模式會影響車輛可使用的道路和速度。另請參閱travel_duration_multiple。
route_modifiers

RouteModifiers

一組要滿足的條件，會影響特定車輛的路徑計算方式。
start_location

LatLng

車輛在收取任何貨物前的位置。如未指定，車輛會從第一個取貨地點開始。如果貨運模型有時間和距離矩陣，則不得指定 start_location。
start_waypoint

Waypoint

代表車輛在收取任何貨物前出發的地理位置。如果未指定 start_waypoint 或 start_location，車輛會從第一個上車地點開始。如果貨運模型有時間和距離矩陣，則不得指定 start_waypoint。
end_location

LatLng

車輛完成最後一次 VisitRequest 後的地理位置。如果未指定，車輛的 ShipmentRoute 會在完成最後一個 VisitRequest 後立即結束。如果貨運模型有時間和距離矩陣，則不得指定 end_location。
end_waypoint

Waypoint

代表車輛完成最後一個 VisitRequest 後的地理位置。如果未指定 end_waypoint 或 end_location，車輛的 ShipmentRoute 會在完成最後一個 VisitRequest 後立即結束。如果貨運模型有時間和距離矩陣，則不得指定 end_waypoint。
start_tags[]

string

指定附加至車輛路線起點的標記。

不得使用空白或重複的字串。
end_tags[]

string

指定附加在車輛路線結尾的標記。

不得使用空白或重複的字串。
start_time_windows[]

TimeWindow

車輛可從出發地點出發的時間範圍，必須在全域時間限制內 (請參閱 ShipmentModel.global_* 欄位)。如未指定，則除了全域時間限制外，沒有其他限制。

屬於相同重複欄位的時間範圍不得重疊或相鄰，且必須依時間順序排列。

只有在單一時間範圍內，才能設定 cost_per_hour_after_soft_end_time 和 soft_end_time。
end_time_windows[]

TimeWindow

車輛抵達目的地時間範圍，必須在全域時間限制內 (請參閱 ShipmentModel.global_* 欄位)。如未指定，則除了全域時間限制外，沒有其他限制。

屬於相同重複欄位的時間範圍不得重疊或相鄰，且必須依時間順序排列。

只有在單一時間範圍內，才能設定 cost_per_hour_after_soft_end_time 和 soft_end_time。
unloading_policy

UnloadingPolicy

車輛強制卸載政策。
load_limits

map<string, LoadLimit>

車輛的容量 (例如重量、體積、棧板數量)。地圖中的鍵是負載類型的 ID，與 Shipment.load_demands 欄位的鍵一致。如果地圖中缺少特定鍵，則對應的容量會視為無限。
cost_per_hour

double

車輛費用：所有費用加總，且必須與 Shipment.penalty_cost 採用相同單位。

車輛路線每小時的費用。這項費用會套用至路線的總時間，包括行程時間、等待時間和拜訪時間。使用 cost_per_hour 而非僅使用 cost_per_traveled_hour 可能會導致額外延遲。
cost_per_traveled_hour

double

車輛路線每小時的行駛費用。這項費用僅適用於路線的行程時間 (即 ShipmentRoute.transitions 中回報的時間)，不包括等待時間和參觀時間。
cost_per_kilometer

double

車輛路線每公里的費用。這筆費用會套用至 ShipmentRoute.transitions 中回報的距離，不會套用至從單一 VisitRequest 的 arrival_location 到 departure_location 隱含行駛的任何距離。
fixed_cost

double

如果使用這輛車處理貨件，則會套用固定費用。
used_if_route_is_empty

bool

這個欄位僅適用於路線上沒有任何貨件的車輛，表示在這種情況下，車輛是否應視為已使用。

如果為 true，車輛會從起點前往終點，即使沒有運送任何貨物，系統也會將起點到終點的行車時間和距離納入考量。

否則車輛不會從起點行駛至終點，且不會為這輛車排定 break_rule 或延誤 (從 TransitionAttributes)。在本例中，車輛的 ShipmentRoute 除了車輛索引和標籤外，不含任何資訊。
route_duration_limit

DurationLimit

這項限制適用於車輛路線的總時長。在特定 OptimizeToursResponse 中，車輛的路線時間長度是 vehicle_end_time 和 vehicle_start_time 之間的差異。
travel_duration_limit

DurationLimit

車輛路線的行車時間限制。在特定 OptimizeToursResponse 中，路線的行程時間是所有 transitions.travel_duration 的總和。
route_distance_limit

DistanceLimit

這項限制會套用至車輛路線的總距離。在特定OptimizeToursResponse中，路線距離是所有transitions.travel_distance_meters的總和。
extra_visit_duration_for_visit_type

map<string, Duration>

指定從 visit_types 字串到時間長度的對應。時間長度是指在指定 visit_types 的就診時間之外，還需要花費的時間。VisitRequest.duration如果指定 cost_per_hour，這段額外時間會產生費用。鍵 (即 visit_types) 不得為空字串。

如果預約要求有多個類型，地圖會為每個類型新增時間長度。
break_rule

BreakRule

說明要對這部車輛強制執行的休息時間表。如果留空，系統就不會為這輛車安排休息時間。
label

string

指定這部車輛的標籤。這個標籤會在回應中以對應 ShipmentRoute 的 vehicle_label 形式回報。
ignore

bool

如為 true，used_if_route_is_empty 必須為 false，且這部車輛會維持未使用狀態。

如果 injected_first_solution_routes 中有車輛遭到忽略，但仍執行出貨作業，則第一個解決方案會略過該作業，但回應中可以執行。

如果出貨作業是由 injected_solution_constraint 中遭忽略的車輛執行，且任何相關取貨/送貨作業都必須留在車輛上 (即未放寬至 RELAX_ALL_AFTER_THRESHOLD 級別)，則系統會在回應中略過該作業。如果貨運的 allowed_vehicle_indices 欄位不為空，且所有允許的車輛都遭到忽略，則系統會在回應中略過該貨運。
travel_duration_multiple

double

指定可用於增加或減少這部車輛行車時間的乘法因子。舉例來說，如果將此值設為 2.0，表示這部車輛較慢，行車時間是標準車輛的兩倍。這個倍數不會影響拜訪時間長度，但如果指定 cost_per_hour 或 cost_per_traveled_hour，則會影響成本。這個值必須介於 [0.001, 1000.0] 之間。如果未設定，車輛為標準車輛，這個倍數會視為 1.0。

警告：套用這個倍數後，系統會將行程時間四捨五入至最接近的秒數，然後再執行任何數值運算，因此較小的倍數可能會導致精確度降低。

另請參閱下方的 extra_visit_duration_for_visit_type。

DurationLimit

定義車輛路線最長時數的限制。這項限制可以是硬性或軟性。

定義軟性限制欄位時，必須同時定義軟性上限門檻和相關聯的費用。

欄位
max_duration

Duration

硬性限制，將時間長度限制在 max_duration 內。
soft_max_duration

Duration

軟性限制不會強制執行時間長度上限，但如果違反規定，路線就會產生費用。這項費用會與模型中定義的其他費用加總，單位相同。

如果已定義，soft_max_duration 必須為非負數。如果也定義了 max_duration，soft_max_duration 必須小於 max_duration。
quadratic_soft_max_duration

Duration

軟性限制不會強制執行時間上限，但如果違反規定，路線就會產生費用，費用與時間的平方成正比。這項費用會與模型中定義的其他費用加總，單位相同。

如果設定 quadratic_soft_max_duration，則必須符合下列條件：

  • 不得為負數。
  • 必須定義 max_duration。
  • quadratic_soft_max_duration 必須小於 max_duration。
  • 兩者差異不得超過一天：max_duration - quadratic_soft_max_duration <= 86400 seconds
cost_per_hour_after_soft_max

double

如果違反 soft_max_duration 門檻，每小時的費用。如果時間長度低於門檻，則額外費用為 0；否則費用會依時間長度而定，如下所示：

  cost_per_hour_after_soft_max * (duration - soft_max_duration)

費用不得為負值。
cost_per_square_hour_after_quadratic_soft_max

double

如果違反 quadratic_soft_max_duration 門檻，每平方小時產生的費用。

如果時間長度低於門檻，則額外費用為 0；否則費用會依時間長度而定，如下所示：

  cost_per_square_hour_after_quadratic_soft_max *
  (duration - quadratic_soft_max_duration)^2

費用不得為負值。

LoadLimit

定義車輛的載重限制，例如「這輛卡車最多只能載運 3500 公斤」。詳情請參閱《load_limits》。

欄位
soft_max_load

int64

負載的軟性限制。詳情請參閱《cost_per_unit_above_soft_max》。
cost_per_unit_above_soft_max

double

如果車輛在路線上的負重超過 soft_max_load，系統會套用下列費用罰款 (每輛車只會套用一次)：(負重 - soft_max_load) * cost_per_unit_above_soft_max。所有費用加總後，必須與 Shipment.penalty_cost 的單位相同。軟性限制只能定義在整個模型中僅適用於取貨或僅適用於送貨的類型。
start_load_interval

Interval

路線開始時車輛可接受的載重間隔。
end_load_interval

Interval

車輛在路線終點可接受的裝載間隔。
max_load

int64

可接受的負載量上限。
cost_per_kilometer

LoadCost

這部車輛每移動一公里，運送一單位負載的成本。這項指標可用於估算燃料消耗量：如果負載是重量 (以牛頓為單位)，則負載*公里具有能量的維度。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。
cost_per_traveled_hour

LoadCost

這輛車每小時的單位負重行駛成本。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。

時間間隔

可接受的載入金額間隔。

欄位
min

int64

可接受的最低負重。必須 ≥ 0。如果兩者都指定，min 必須 ≤ max。
max

int64

可接受的負載上限。必須 ≥ 0。如果未指定，則負載上限不受這則訊息限制。如果兩者都已指定，則 min 必須 ≤ max。

LoadCost

在 Transition 期間移動一單位負載的費用。特定負載的費用是下列兩部分的總和：

  • min(load, load_threshold) * cost_per_unit_below_threshold
  • max(0, load - load_threshold) * cost_per_unit_above_threshold

根據這項成本，解決方案會優先滿足高需求，或最後才滿足高需求。舉例來說，如果車輛有

load_limit {
  key: "weight"
  value {
    cost_per_kilometer {
      load_threshold: 15
      cost_per_unit_below_threshold: 2.0
      cost_per_unit_above_threshold: 10.0
    }
  }
}

路線為 start、pickup、pickup、delivery、delivery、end，並包含以下轉換：

transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 20 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }

則此 LoadCost 產生的費用為 (下方費用 * 下方負重 * 公里數 + 上方費用 * 上方負重 * 公里數)

  • 轉場 0：0.0
  • 轉場 1：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 轉換 2：2.0 * 15 * 1.0 + 10.0 * (20 - 15) * 1.0 = 80.0
  • 轉場 3：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 轉場 4：0.0

因此路線上的 LoadCost 為 120.0。

不過，如果路線是 start、pickup、delivery、pickup、delivery、end，且有轉換：

transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }

則這項 LoadCost 產生的費用為

  • 轉場 0：0.0
  • 轉場 1：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 轉場 2：0.0
  • 轉場 3：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • 轉場 4：0.0

這裡的路線 LoadCost 為 40.0。

LoadCost，因此解決方案的成本較高。

實驗功能：詳情請參閱 https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request。

欄位
load_threshold

int64

負載量超過此值後，移動單位負載的費用會從 cost_per_unit_below_threshold 變更為 cost_per_unit_above_threshold。必須大於或等於 0。
cost_per_unit_below_threshold

double

移動一個負載單位的成本，適用於 0 到門檻之間的每個單位。必須是有限值，且 >= 0。
cost_per_unit_above_threshold

double

超過門檻的每個負載單位的移動成本。在門檻 = 0 的特殊情況下，這是每單位的固定費用。必須是有限值，且 >= 0。

TravelMode

車輛可使用的交通方式。

這些應是 Google Maps Platform Routes API 交通方式的子集，請參閱：https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteTravelMode

注意：WALKING 路線目前為 Beta 版，有時可能缺少明確的人行道或行人路徑。您必須在應用程式中顯示的所有步行路線中，向使用者顯示這項警告。

列舉
TRAVEL_MODE_UNSPECIFIED 未指定交通方式，相當於 DRIVING。
DRIVING 與行車路線 (汽車等) 相對應的交通方式。
WALKING 與步行路線相應的交通方式。

UnloadingPolicy

車輛卸貨方式的政策。僅適用於同時有取貨和送貨的貨件。

其他出貨作業可發生在路線上的任何位置，不受 unloading_policy 限制。

列舉
UNLOADING_POLICY_UNSPECIFIED 卸貨政策未指定，只要在取貨後送達即可。
LAST_IN_FIRST_OUT 送達順序必須與取貨順序相反
FIRST_IN_FIRST_OUT 送達順序必須與取貨順序相同

VehicleFullness

VehicleFullness 是計算車輛裝載量的指標。每個 VehicleFullness 欄位的值介於 0 和 1 之間，計算方式為上限指標欄位 (例如 AggregatedMetrics.travel_distance_meters) 與相關車輛限制 (例如 Vehicle.route_distance_limit) 的比率 (如有)。否則，裝載量比率會維持未設定狀態。如果限制為 0，欄位會設為 1。注意：如果路線受到交通狀況影響而無法通行，部分原始裝載量比率可能會超過 1.0，例如車輛可能超過距離限制。在這些情況下，我們會將裝載量值設為 1.0。

欄位
max_fullness

double

這則訊息中所有其他欄位的最大值。
distance

double

AggregatedMetrics.travel_distance_meters 與 Vehicle.route_distance_limit 的比率。如果未設定 Vehicle.route_distance_limit，這個欄位也會未設定。
travel_duration

double

[AggregatedMetrics.travel_duration_seconds][] 與 Vehicle.travel_duration_limit 的比率。如果未設定 Vehicle.travel_duration_limit，這個欄位也會未設定。
active_duration

double

[AggregatedMetrics.total_duration_seconds][] 與 Vehicle.route_duration_limit 的比率。如果 Vehicle.route_duration_limit 未設定，這個欄位也會未設定。
max_load

double

所有類型的 [AggregatedMetrics.max_load][] 和各自 Vehicle.load_limits 之間的最大比率。如果所有 Vehicle.load_limits 欄位都未設定，這個欄位也會未設定。
active_span

double

特定車輛的比率 (vehicle_end_time - vehicle_start_time) / (latest_vehicle_end_time - earliest_vehicle_start_time)。如果沒有分母，則會改用 (ShipmentModel.global_end_time - ShipmentModel.global_start_time)。

途經點

封裝路線控點。中途點會標示 VisitRequest 的抵達和出發地點，以及 Vehicle 的起點和終點。

欄位
side_of_road

bool

(選用步驟) 表示這個路線控點的位置偏好車輛停靠在道路的特定一側。設定這個值後，路線會經過該位置，讓車輛停靠在道路中心偏向該位置的一側。這個選項不適用於「步行」交通模式。
vehicle_stopover

bool

指出路線控點是供車輛停靠的地點，目的是接送乘客。這個選項僅適用於「DRIVING」交通方式，且「location_type」為「location」。

實驗性：這個欄位的行為或存在狀態日後可能會變更。
聯集欄位 location_type。表示位置的不同方式。location_type 只能是下列其中一項：
location

Location

使用地理座標指定的點，包括選用的航向。
place_id

string

與航點相關聯的 POI 地點 ID。

使用地點 ID 指定 VisitRequest 的抵達或出發地點時，請使用足夠具體的地點 ID，以利判斷導航至該地點的 LatLng 位置。舉例來說，代表建築物地點 ID 適合使用，但代表道路的地點 ID 則不建議使用。