Package google.maps.routeoptimization.v1

索引

RouteOptimization

用於最佳化車輛導覽的服務。

特定類型欄位的有效性：

  • google.protobuf.Timestamp
    • 時間以 Unix 時間表示：自 1970-01-01T00:00:00+00:00 起算的秒數。
    • 秒數必須介於 [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。如果要求失敗，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，這是一組由車輛執行的路線，可盡量降低整體成本。

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。

授權範圍

需要下列 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 欄位類型為 OptimizeToursUriMetadata。如果成功，response 欄位類型為 OptimizeToursUriResponse。

授權範圍

需要下列 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 小時的滑動時間範圍內，必須至少有一次至少一小時的休息時間」，則該範例會轉譯為以下 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 上所有造訪的開始時間和順序都會受到完全限制，且無法在這些路線中插入或新增造訪。此外，車輛在 routes 中的開始和結束時間會受到完全限制，除非車輛是空的 (即沒有停靠點，且在模型中將 used_if_route_is_empty 設為 false)。

relaxations(i).level 指定套用至造訪 #j 的限制放寬等級，且符合以下條件：

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

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

  • vehicle_start_time >= relaxations(i).threshold_time AND
  • 如果符合下列條件，relaxations(i).threshold_visit_count == 0 和車輛結束時間會放寬至 relaxations(i).level：
  • vehicle_end_time >= relaxations(i).threshold_time AND
  • route.visits_size() + 1 >= relaxations(i).threshold_visit_count

如要在造訪符合 threshold_visit_count 或 threshold_time 時套用放寬等級，請新增兩個具有相同 level 的 relaxations：一個僅設定 threshold_visit_count，另一個僅設定 threshold_time。如果某次造訪符合多個relaxations的條件，系統會套用最寬鬆的層級。因此，從車輛起點到車輛終點，放寬程度會越來越寬鬆，也就是說，放寬程度會隨著路線進度而增加。

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

欄位
level

Level

在 threshold_time當天或之後，且至少 threshold_visit_count時，適用的限制放寬等級。
threshold_time

Timestamp

可套用放寬條件 level 的時間 (含)。
threshold_visit_count

int32

達到或超過這個造訪次數後，系統可能會套用放寬條件 level。如果 threshold_visit_count 為 0 (或未設定)，則 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 (或 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

如果設定這個值，要求的期限 (請參閱 https://grpc.io/blog/deadlines) 最多可達 60 分鐘。否則，最長期限只有 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

截斷傳回的驗證錯誤數量。這類錯誤通常會附加至 INVALID_ARGUMENT 錯誤酬載，做為 BadRequest 錯誤詳細資料 (https://cloud.google.com/apis/design/errors#error_details))，除非 solving_mode=VALIDATE_ONLY：請參閱 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 訊息。如果 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 的 proto 路徑，例如「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

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

Uri

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

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) 組合，因為新的錯誤會隱藏舊的錯誤。例如，請參閱「多項錯誤」。
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 之間有一對一的對應關係 (當 code != "UNSPECIFIED" 時)。

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

string

可能包含欄位的值。這項功能不一定可用。請勿依賴這項功能，僅限用於手動偵錯模型。

FieldReference

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

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 的 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

指定模型中使用的時間長度和距離矩陣。如果這個欄位留空，系統會根據 use_geodesic_distances 欄位的值，改用 Google 地圖或測地線距離。如果不是空白，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」。
  • 1 個 locC 的取貨造訪要求。
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_types 組合 (請參閱 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 才能開始。

多個優先順序可以參照相同 (或相關) 事件，例如「在 A 交付後取件 B」和「在取件 B 後取件 C」。

此外，只有在執行兩項運送作業時，優先順序才會生效，否則會遭到忽略。

欄位
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 具有唯一性，且必須是緊接在下次造訪 (或車輛結束) 之前的連續時間。因此，只要知道延遲時間長度，就能知道開始和結束時間。
  • BREAKS 是連續且不重疊的時間。回應會指定每個廣告插播的開始時間和持續時間。
  • 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 的取貨或送貨欄位中 VisitRequest 的索引 (請參閱 is_pickup)。
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。只有在啟用多模式最佳化時，系統才會使用停靠站造訪。

列舉
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

根據 shipment_type 指定運送作業之間的需求。具體規定由模式定義。

欄位
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 會有超過 1 個元素。略過的運送作業不得有重複的原因，也就是除了 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

指向資源的通用資源識別碼，可由 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

定義車輛的載重限制，例如「這輛卡車最多只能載重 3, 500 公斤」。詳情請參閱《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
    }
  }
}

路線為起點、取貨、取貨、送貨、送貨、終點，轉移如下：

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產生的費用為 (cost_below * load_below * 公里數 + cost_above * load_above * 公里數)

  • transition 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
  • transition 4: 0.0

因此，路線的 LoadCost 為 120.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 }
transition { vehicle_load['weight'] { amount: 10 }
             travel_distance_meters: 1000.0 }
transition { vehicle_load['weight'] { amount: 0 }
             travel_distance_meters: 1000.0 }

則這項 LoadCost 產生的費用為

  • transition 0: 0.0
  • 轉換 1：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • transition 2: 0.0
  • 轉換 3：2.0 * 10 * 1.0 + 10.0 * 0 * 1.0 = 20.0
  • transition 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 的抵達和出發位置，以及車輛的起點和終點位置。

欄位
side_of_road

bool

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

bool

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

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

Location

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

string

與路線控點相關聯的搜尋點地點 ID。

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