Package google.maps.routeoptimization.v1

int32

已完成的出貨數量。請注意，每組「上車地點」和「下車地點」只會計入一次。

Duration

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

Duration

路線或解決方案的總等候時間長度。

Duration

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

Duration

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

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]

double

路線或解決方案的總行程距離。

map<string, VehicleLoad>

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

string

必要欄位。要呼叫的目標專案和位置。

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

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

AsyncModelConfig

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

string

選用設定。使用者定義的模型名稱，可做為使用者追蹤模型的別名。

InputConfig

必要欄位。輸入模型的相關資訊。

OutputConfig

必要欄位。所需的輸出位置資訊。

BreakRequest

中斷序列。請參閱 BreakRequest 訊息。

FrequencyConstraint

可能會套用多個 FrequencyConstraint。這些值都必須符合這個 BreakRule 的 BreakRequest。請參閱 FrequencyConstraint。

Timestamp

必要欄位。休息時間開始時間的下限 (包含在內)。

Timestamp

必要欄位。休息時間開始的上限 (包含在內)。

Duration

必要欄位。插播時間長度下限。必須為正數。

Duration

必要欄位。此限制的插播時間長度下限。非負值。請參閱 FrequencyConstraint 的說明。

Duration

必要欄位。路徑中不含 duration >= min_break_duration 中斷的部分，允許的時間間隔上限。必須為正數。

int64

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

int64

軟性限制不會強制執行最大距離限制，但如果違反限制，則會產生費用，並與模型中定義的其他費用相加，使用相同的單位。

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

double

每公里費用 (最高 soft_max_meters)，公式如下：

  min(distance_meters, soft_max_meters) / 1000.0 *
  cost_per_kilometer_below_soft_max.

route_distance_limit 不支援這項費用。

double

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

  (distance_meters - soft_max_meters) / 1000.0 *
  cost_per_kilometer_above_soft_max.

費用必須為非負值。

string

必要欄位。Google Cloud Storage URI。

string

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

ShipmentRoute

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

SkippedShipment

要插入的解決方案已略過出貨。部分項目可能會從原始解決方案中省略。請參閱 routes 欄位。

ConstraintRelaxation

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

Relaxation

所有造訪限制放寬項目，會套用至 vehicle_indices 中含有車輛的路線造訪。

int32

指定要套用造訪限制 relaxations 的車輛索引。如果留空，系統會將其視為預設值，並將 relaxations 套用至其他 constraint_relaxations 未指定的所有車輛。最多只能有一個預設值，也就是最多只能有一個限制放寬欄位可為空白 vehicle_indices。車輛索引只能列出一次，即使在多個 constraint_relaxations 中也是如此。

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

Level

在 threshold_time 之後或之後，且至少滿足 threshold_visit_count 的條件時，套用的限制放寬程度。

Timestamp

可套用放寬 level 的時間點或之後。

int32

系統可在多少次造訪後套用放寬 level 的數量。如果 threshold_visit_count 為 0 (或未設定)，level 可能會在車輛啟動時直接套用。

如果是 route.visits_size() + 1，level 可能只會套用至車輛端。如果超過 route.visits_size() + 1，則該路徑將完全不套用 level。

DataFormat

必要欄位。輸入資料格式。

GcsSource

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

LatLng

航點的地理座標。

int32

與流量方向相關的指南針方位。這個值用於指定接送和下車地點的道路兩側。方向值的範圍為 0 到 360，其中 0 指定正北方向，90 指定正東方向，以此類推。

string

必要欄位。要呼叫的目標專案或位置。

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

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

Duration

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

對於非同步要求，伺服器會在逾時前產生解決方案 (如果可行)。

ShipmentModel

解決運送模型。

SolvingMode

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

SearchMode

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

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 中，系統就會允許該車輛。

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

InjectedSolutionConstraint

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

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

ShipmentRoute

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

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

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

這個欄位不得與 injected_first_solution_routes 或 injected_solution_constraint 搭配使用。

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

bool

如果為 true：

• 使用 ShipmentRoute.vehicle_label 而非 vehicle_index，比對已插入解決方案中的路線與要求中的車輛；如果非空白，則重複使用原始 ShipmentRoute.vehicle_index 與新 ShipmentRoute.vehicle_index 的對應項目，以更新 ConstraintRelaxation.vehicle_indices，但對應項目必須明確無誤 (也就是說，多個 ShipmentRoute 不得共用相同的原始 vehicle_index)。
• 使用 ShipmentRoute.Visit.shipment_label 而非 shipment_index，將注入的解決方案中的造訪與要求中的出貨進行比對。
• 使用 SkippedShipment.label 而非 SkippedShipment.index，將注入的解決方案中略過的出貨項目與要求出貨項目進行比對。

這項解釋適用於 injected_first_solution_routes、injected_solution_constraint 和 refresh_details_routes 欄位。當建立解決方案後，要求中的運送或車輛索引發生變更時，即可使用這項方法。這可能是因為運送或車輛已從要求中移除或新增。

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

• 要求中的 Vehicle.label；
• 要求中的 Shipment.label；
• ShipmentRoute.vehicle_label 在注射溶液中；
• 插入的解決方案中的 SkippedShipment.label 和 ShipmentRoute.Visit.shipment_label (除了接送/送達訪問組合，其 shipment_label 必須出現兩次)。

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

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

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

bool

在計算 ShipmentRoute 欄位 Transition.travel_duration、Visit.start_time 和 vehicle_end_time、設定 ShipmentRoute.has_traffic_infeasibilities 欄位，以及計算 OptimizeToursResponse.total_cost 欄位時，請考慮使用流量估算值。

bool

如果為 true，回應 ShipmentRoute 會填入多邊形。

bool

如果為 true，系統會在回應 ShipmentRoute.transitions 中填入多邊形和路線符記。

bool

如果設定了這個值，要求的期限 (請參閱 https://grpc.io/blog/deadlines) 最多可達 60 分鐘。否則，最長期限僅為 30 分鐘。請注意，長時間存在的要求有較高 (但仍很小) 的中斷風險。

bool

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

string

可能用於識別此要求的標籤，會在 OptimizeToursResponse.request_label 中回報。

double

當 use_geodesic_distances 為 true 時，必須設定這個欄位，並定義用於計算行程時間的速度。這個值必須至少為 1.0 公尺/秒。

int32

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

ShipmentRoute

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

string

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

SkippedShipment

略過所有出貨的清單。

OptimizeToursValidationError

我們獨立偵測到的所有驗證錯誤清單。請參閱「MULTIPLE ERRORS」一節，瞭解 OptimizeToursValidationError 訊息的說明。在 solving_mode 為 DEFAULT_SOLVE 的情況下，這會加入警告，而非錯誤。

Metrics

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

AggregatedMetrics

匯總路線。每個指標都是所有同名 ShipmentRoute.metrics 欄位的總和 (或負載的最大值)。

int32

略過的強制貨件數量。

int32

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

Timestamp

二手車最早的開始時間，計算方式為 ShipmentRoute.vehicle_start_time 中所有二手車的最小值。

Timestamp

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

map<string, double>

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

double

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

int32

驗證錯誤是由一組一律存在的值 (code、display_name) 定義。

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

MULTIPLE ERRORS：如果發生多項錯誤，驗證程序會嘗試輸出其中幾項。這項程序與編譯器相似，並非完美無瑕。部分驗證錯誤會導致「致命」錯誤，也就是會停止整個驗證程序。display_name="UNSPECIFIED" 錯誤就是這種情況。部分錯誤可能會導致驗證程序略過其他錯誤。

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

string

錯誤的顯示名稱。

FieldReference

錯誤內容可能涉及 0 個、1 個 (大多數情況) 或更多欄位。舉例來說，如要參照車輛 #4 和貨件 #2 的首次取件，可以執行以下操作：

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

不過，請注意，fields 的基數不應因特定錯誤代碼而變更。

string

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

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

string

可能包含欄位的值。但不一定適用於所有情況。請務必不要依賴這項功能，並且只在手動模型偵錯時使用。

string

欄位名稱，例如「vehicles」。

FieldReference

必要時，可遞迴巢狀子欄位。

int32

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

string

若欄位為對應項，則為索引鍵。

DataFormat

必要欄位。輸出資料格式。

GcsDestination

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

bool

指定是否在合理情況下避開收費道路。系統會優先提供不含收費道路的路線。僅適用於機動運輸模式。

bool

指定是否在合理情況下避開高速公路。系統會優先選擇不經過高速公路的路線。僅適用於機動運輸模式。

bool

指定是否在合理情況下避開渡輪。系統會優先提供不含渡輪的路線。僅適用於機動運輸模式。

bool

選用設定。指定是否在合理情況下避免室內導航。系統會優先考量不含室內導航功能的路線。僅適用於 WALKING 行程模式。

string

使用者定義的運送貨物顯示名稱。長度上限為 63 個半形字元，可以使用 UTF-8 字元。

VisitRequest

與運送作業相關的取貨替代方案集合。如果未指定，車輛只需要前往與送貨地點相對應的位置即可。

VisitRequest

與運送作業相關的替代運送選項集合。如果未指定，車輛只需前往與乘客上車地點相對應的位置即可。

map<string, Load>

裝載貨物的負載需求 (例如重量、體積、貨架數量等)。地圖中的鍵應為描述對應負載類型的 ID，最好也包含單位。例如："weight_kg"、"volume_gallons"、"pallet_count" 等。如果指定的鍵未顯示在對應的載入中，系統會將該載入視為空值。

int32

可能執行這項運送作業的車輛組合。如果留空，則所有車輛都可能執行該動作。車輛會依據 ShipmentModel 的 vehicles 清單中的索引指定。

double

指定透過每輛車輛運送這項貨物時產生的費用。如果已指定，則必須具備下列其中一種條件：

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

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

int32

costs_per_vehicle 適用的車輛索引。如果不為空白，則必須與 costs_per_vehicle 具有相同數量的元素。車輛索引只能指定一次。如果車輛從 costs_per_vehicle_indices 中排除，其費用為零。

Duration

指定相較於從上車地點到送達地點的最短路徑，最多可繞行的絕對時間。如果指定了這個值，則必須為非負值，且運送作業至少必須包含一個取件和一個送達作業。

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

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

如果在同一筆訂單上同時指定相對和絕對限制，系統會為每個可能的取件/送達組合使用較嚴格的限制。自 2017 年 10 月起，系統只會在行程時間不受車輛影響時支援繞道。

Duration

指定從商品開始取件到開始送達的時間長度上限。如果指定了這項屬性，則該值必須為非負值，且運送作業至少必須包含一個取件和一個送達作業。這不取決於你為取件和送件選取的替代方案，也不取決於車輛速度。您可以同時指定這項限制和最大繞行限制：解決方案會遵循這兩項規範。

string

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

與 visit_types 不同，後者是針對單一造訪指定：屬於同一筆訂單的所有取貨/送貨都會共用相同的 shipment_type。

string

指定此運送單的標籤。這個標籤會在對應 ShipmentRoute.Visit 的 shipment_label 回應中回報。

bool

如果為 True，則略過這項出貨作業，但不會套用 penalty_cost。

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

系統允許忽略在 injected_first_solution_routes 或 injected_solution_constraint 中執行的運送作業；解決程序會從執行路線中移除相關的取貨/送貨拜訪。precedence_rules 參照的忽略出貨項目也會遭到忽略。

double

如果無法完成運送，這筆罰款會加到路線的整體費用中。如果運送員前往其中一個提貨和送貨地點，系統就會將該筆訂單視為完成。費用可以使用模型中所有其他費用相關欄位使用的單位來表示，且必須為正值。

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

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 月起，系統只會在行程時間不受車輛影響時支援繞道。

int64

執行對應造訪的車輛載重量會有所不同。由於這是整數，建議使用者選擇適當的單位，以免精確度降低。必須大於或等於 0。

LatLng

車輛執行此 VisitRequest 時抵達的地理位置。如果運送模型含有時間距離矩陣，請勿指定 arrival_location。

Waypoint

車輛執行這項 VisitRequest 時抵達的路線點。如果運送模型含有時間距離矩陣，請勿指定 arrival_waypoint。

LatLng

車輛完成這個 VisitRequest 後的出發地點。如果與 arrival_location 相同，可以省略。如果運送模型含有時間距離矩陣，請勿指定 departure_location。

Waypoint

車輛完成這個 VisitRequest 後的出發路徑點。如果與 arrival_waypoint 相同，可以省略。如果運送模型含有時間距離矩陣，請勿指定 departure_waypoint。

string

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

TimeWindow

限制造訪時間的時間區間。請注意，車輛可能會在到達時間回溯期過後離開，也就是說，到達時間 + 車程時間不一定會在回溯期內。如果車輛在 TimeWindow.start_time 之前抵達，乘客可能會等待一段時間。

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

時間區間必須不重疊，也就是說，每個時間區間都不得與其他時間區間重疊或相鄰，且必須依遞增順序排列。

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

Duration

行程時間，也就是車輛從抵達到離開之間的時間 (會加入可能的等候時間；請參閱 time_windows)。

double

在車輛路線上處理這項拜訪要求的費用。你可以使用這項功能，為每項替代取貨或運送服務支付不同的費用。這個成本必須與 Shipment.penalty_cost 相同單位，且不得為負數。

map<string, Load>

載入此造訪要求的需求。這與 Shipment.load_demands 欄位相同，但只會套用至這個 VisitRequest，而非整個 Shipment。這裡列出的請求會加入 Shipment.load_demands 中列出的請求。

string

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

一個類型只能出現一次。

string

指定這個 VisitRequest 的標籤。這個標籤會在回應中以對應的 ShipmentRoute.Visit 中的 visit_label 回報。

Shipment

模型中必須執行的運送作業集合。

Vehicle

可用於執行拜訪的車輛組合。

Timestamp

模型的全球開始和結束時間：系統不會將範圍外的時間視為有效時間。

模型的時間跨度不得超過一年，也就是 global_end_time 和 global_start_time 之間的時間差不得超過 31536000 秒。

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

Timestamp

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

double

整體時間表的「全球時間長度」是所有車輛最早有效開始時間和最晚有效結束時間的差距。使用者可以為該數量指派每小時成本，以便盡早完成工作。此費用必須與 Shipment.penalty_cost 使用相同的單位。

DurationDistanceMatrix

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

使用範例：

• 有兩個位置：locA 和 locB。
• 1 輛車輛的路線起點和終點皆為 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
    }
  }
}

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 就必須非空白。

string

定義時間和距離矩陣目的地的標記；duration_distance_matrices(i).rows(j).durations(k) (resp. duration_distance_matrices(i).rows(j).meters(k)) 會定義矩陣 i 中，從標記為 duration_distance_matrix_src_tags(j) 的造訪到標記為 duration_distance_matrix_dst_tags(k) 的造訪之間的旅程時間 (或距離)。

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

TransitionAttributes

新增至模型的轉場屬性。

ShipmentTypeIncompatibility

不相容的 shipment_types 組合 (請參閱 ShipmentTypeIncompatibility)。

ShipmentTypeRequirement

shipment_type 需求集 (請參閱 ShipmentTypeRequirement)。

PrecedenceRule

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

int32

限制有效車輛數量上限。如果車輛的路線至少執行一筆運送作業，就會視為處於運作狀態。在駕駛人數少於車輛數量，且車隊車輛種類不一的情況下，您可以使用這個選項限制路線數量。系統就會選取最適合的車輛子集。必須為正值。

Row

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

string

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

每個車輛啟動都必須與單一矩陣相符，也就是說，其中的 start_tags 欄位必須與矩陣的 vehicle_start_tag 相符 (且只相符一個矩陣)。

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

Duration

特定資料列的時間長度值。必須與 ShipmentModel.duration_distance_matrix_dst_tags 具有相同數量的元素。

double

特定資料列的距離值。如果模型中沒有任何成本或限制參照距離，可以將這個屬性設為空白；否則，這個屬性必須包含與 durations 相同數量的元素。

bool

指出「first」事件是否為放送事件。

bool

指出「第二」事件是否為遞送事件。

Duration

「first」和「second」事件之間的偏移量。可以是負值。

int32

「first」事件的出貨索引。必須指定這個欄位。

int32

「second」事件的出貨索引。必須指定這個欄位。

int32

執行路線的車輛，可透過來源 ShipmentModel 中的索引識別。

string

執行此路線的車輛標籤，等同於 ShipmentModel.vehicles(vehicle_index).label (如有指定)。

Timestamp

車輛開始行駛的時間。

Timestamp

車輛完成路線的時間。

Visit

代表路線的排序造訪序列。visits[i] 是路線的第 i 次造訪。如果這個欄位為空白，系統會將車輛視為未使用。

Transition

路線的轉場效果排序清單。

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 的到達時間可能會比目前的時間範圍晚。此外，由於預估的移動時間增加，且訪問或休息時間窗口受限，因此休息時間可能會與訪問時間重疊。

EncodedPolyline

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

Break

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

AggregatedMetrics

此路線的時間長度、距離和載入指標。AggregatedMetrics 的欄位會根據上下文，對所有 ShipmentRoute.transitions 或 ShipmentRoute.visits 加總。

map<string, double>

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

double

路線的總費用。費用圖表中所有費用的總和。

Timestamp

廣告插播的開始時間。

Duration

休息時間長度。

string

代表折線編碼點的字串。

Duration

這段轉換期間的旅遊時間。

double

轉換期間移動的距離。

bool

當透過 OptimizeToursRequest.consider_road_traffic 要求流量，但無法擷取 Transition 的流量資訊時，這個布林值會設為 true。這可能是暫時性問題 (即時交通流量伺服器偶爾發生故障) 或永久性問題 (該位置沒有資料)。

Duration

套用至此轉場效果的延遲時間總和。如果有延遲時間，則會在下一個事件 (造訪或車輛結束) 之前的 delay_duration 秒開始計時。查看《TransitionAttributes.delay》。

Duration

在這個轉換期間內發生的片段持續時間總和 (如有)。每個廣告插播的開始時間和持續時間詳細資料會儲存在 ShipmentRoute.breaks 中。

Duration

在轉換期間等待的時間。等待時間長度與閒置時間相對應，不包含休息時間。另請注意，這段等待時間可能會分為數個不連續的間隔。

Duration

轉場效果的總時間長度 (僅供參考)。等於：

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

Timestamp

此轉場效果的開始時間。

EncodedPolyline

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

string

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

map<string, VehicleLoad>

在這個轉換期間載入的車輛，每個類型都會顯示在該車輛的 Vehicle.load_limits 中，或是在這個路線上執行的某些出貨作業中，有非零值的 Shipment.load_demands。

在第一次轉換期間的負載，是車輛路線的起始負載。接著，在每次造訪後，系統會根據造訪是取件或送件，增加或減少造訪的 load_demands，以便載入下一個轉換。

int64

特定車輛類型的負載量。負載單位通常會以類型表示。詳情請參閱《Transition.vehicle_loads》。

int32

來源 ShipmentModel 中 shipments 欄位的索引。

bool

如果為 true，則表示該造訪對應至 Shipment 的接送。否則，則對應至提交內容。

int32

Shipment 的「pickup」或「delivery」欄位中 VisitRequest 的索引 (請參閱 is_pickup)。

Timestamp

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

map<string, Load>

總訪客負載需求是出貨和訪客要求 load_demands 的總和。如果造訪是指向外送訂單，則值為負值。需求的回報類型與 Transition.loads 相同 (請參閱此欄位)。

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.

string

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

string

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

string

不相容類型的清單。兩個出貨項目在列出的 shipment_types 中不相容。

IncompatibilityMode

套用至不相容項目的模式。

string

dependent_shipment_types 所需的替代運送類型清單。

string

所有貨物類型在 dependent_shipment_types 欄位中，至少需要有一個 required_shipment_type_alternatives 類型的貨物，才能在同一條路線中進行拜訪。

注意：系統不允許要求鏈結，例如 shipment_type 依附自身。

RequirementMode

套用至需求的模式。

int32

該索引會對應至來源 ShipmentModel 中的出貨索引。

string

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

Reason

列出略過運送的原因。請參閱 Reason 上方的留言。如果我們無法瞭解訂單遭到略過的原因，就不會設定原因。

Code

請參閱程式碼的註解。

string

如果原因代碼為 DEMAND_EXCEEDS_VEHICLE_CAPACITY，請記錄超出容量的一種容量類型。

int32

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

Timestamp

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

Timestamp

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

Timestamp

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

Timestamp

時間範圍的軟性結束時間。

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 時才能設定這個欄位。

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 時才能設定這個欄位。

string

定義這些屬性適用的 (src->dst) 轉場組合。

來源造訪或車輛啟動活動的 VisitRequest.tags 或 Vehicle.start_tags 必須包含 src_tag，或不包含 excluded_src_tag (視這兩個欄位是否為空白而定)，才能與來源造訪或車輛啟動活動相符。

string

請參閱 src_tag。src_tag 和 excluded_src_tag 中必須有一個值不為空白。

string

只有在 VisitRequest.tags 或 Vehicle.end_tags 包含 dst_tag 或不包含 excluded_dst_tag 時，才會與目的地造訪或車輛結束相符 (取決於這兩個欄位中哪一個非空白)。

string

請參閱 dst_tag。dst_tag 和 excluded_dst_tag 中必須有一個值不為空白。

double

指定執行此轉換作業的費用。此值的單位與模型中的所有其他成本相同，且不得為負數。這筆費用會加上所有現有費用。

double

指定在執行這項轉換作業時，以每公里為單位計算的費用，並套用至實際行駛的距離。會加總車輛上指定的所有 Vehicle.cost_per_kilometer。

DistanceLimit

指定執行此轉場效果時的移動距離限制。

自 2021 年 6 月起，我們只支援軟性限制。

Duration

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

這項延遲一律會發生在完成來源造訪「後」和開始目的地造訪「前」。

string

車輛的使用者定義顯示名稱。長度上限為 63 個半形字元，可以使用 UTF-8 字元。

TravelMode

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

RouteModifiers

一組滿足條件，影響系統為特定車輛計算路線的方式。

LatLng

車輛開始載運貨物的地理位置。如未指定，車輛會在第一趟上車地點開始行駛。如果運送模型含有時間和距離矩陣，請勿指定 start_location。

Waypoint

路徑點代表車輛在取件前所在的地理位置。如果未指定 start_waypoint 或 start_location，車輛會在第一個上車地點開始行駛。如果運送模型含有時間和距離矩陣，請勿指定 start_waypoint。

LatLng

車輛完成最後一次 VisitRequest 後的終點地理位置。如果未指定，車輛的 ShipmentRoute 會在完成最後一次 VisitRequest 後立即結束。如果運送模型含有時間和距離矩陣，請勿指定 end_location。

Waypoint

路標代表車輛完成最後一次 VisitRequest 後的終點地理位置。如果未指定 end_waypoint 或 end_location，車輛的 ShipmentRoute 會在完成最後一次 VisitRequest 後立即結束。如果運送模型含有時間和距離矩陣，請勿指定 end_waypoint。

string

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

不得使用空字串或重複的字串。

string

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

不得使用空字串或重複的字串。

TimeWindow

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

屬於相同重複欄位的時間範圍必須不重疊，也就是說，任何時間範圍都不能與其他時間範圍重疊或相鄰，且必須按照時間順序排列。

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

TimeWindow

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

屬於相同重複欄位的時間範圍必須不重疊，也就是說，任何時間範圍都不能與其他時間範圍重疊或相鄰，且必須按照時間順序排列。

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

UnloadingPolicy

車輛的卸載政策。

map<string, LoadLimit>

車輛的容量 (例如重量、體積、貨架數量)。地圖中的鍵是負載類型的 ID，與 Shipment.load_demands 欄位的鍵一致。如果這個對應表中沒有特定鍵，則系統會將對應的容量視為無限。

double

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

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

double

車輛路線的每小時行駛費用。這項費用只會套用在路線的行程時間 (即 ShipmentRoute.transitions 中回報的時間)，不包括等候時間和造訪時間。

double

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

double

如果這輛車輛用於處理運送作業，就會收取固定費用。

bool

這個欄位只會套用至路線未提供任何貨運服務的車輛。指出在這種情況下，車輛是否應視為二手車。

如果為 true，即使車輛沒有運送任何貨物，也會從起點前往終點，且會考量從起點到終點的時間和距離成本。

否則，車輛就不會從起點前往終點，且系統不會為該車輛安排 break_rule 或延遲 (從 TransitionAttributes 開始)。在這種情況下，車輛的 ShipmentRoute 只包含車輛索引和標籤，不含其他資訊。

DurationLimit

限制車輛路線的總時間。在特定 OptimizeToursResponse 中，車輛的路線時間長度是 vehicle_end_time 和 vehicle_start_time 的差異。

DurationLimit

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

DistanceLimit

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

map<string, Duration>

指定從 visit_types 字串到持續時間的對應項目。時間長度是指在指定 visit_types 的造訪中，除了 VisitRequest.duration 之外所需的時間。如果指定 cost_per_hour，這段額外的造訪時間會增加成本。鍵 (例如 visit_types) 不得為空字串。

如果造訪要求包含多種類型，地圖會為每種類型新增一段時間。

BreakRule

說明要對這輛車輛強制執行的休息時間表。如果為空白，則不會為這輛車輛安排休息時間。

string

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

bool

如果為 true，used_if_route_is_empty 必須為 false，且這輛車輛仍未使用。

如果在 injected_first_solution_routes 中，運送作業是由已略過的車輛執行，則系統會在第一個解決方案中略過該作業，但可在回應中執行。

如果運送作業是由 injected_solution_constraint 中遭到忽略的車輛執行，且任何相關的接送/送達作業都受到限制，必須留在車輛上 (也就是未放寬至 RELAX_ALL_AFTER_THRESHOLD 層級)，系統會在回應中略過該作業。如果運送單有非空白的 allowed_vehicle_indices 欄位，且所有允許的車輛都遭到忽略，系統就會在回應中略過該運送單。

double

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

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

另請參閱下方的 extra_visit_duration_for_visit_type。

Duration

硬性限制，限制片段長度不得超過 max_duration。

Duration

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

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

Duration

軟性限制不會強制執行最大時間長度限制，但如果違反限制，路線就會產生費用，且費用會隨著時間呈現平方關係。這項費用會與模型中定義的其他費用相加，並使用相同的單位。

如果已定義，quadratic_soft_max_duration 不得為負數。如果同時定義了 max_duration，quadratic_soft_max_duration 必須小於 max_duration，且兩者之間的差距不得超過一天：

max_duration - quadratic_soft_max_duration <= 86400 seconds

double

違反 soft_max_duration 門檻時，每小時產生的費用。如果時間長度低於門檻，額外費用為 0，否則費用取決於時間長度，如下所示：

  cost_per_hour_after_soft_max * (duration - soft_max_duration)

費用必須為非負值。

double

違反 quadratic_soft_max_duration 門檻時，每平方小時的費用。

如果時間長度低於門檻，額外費用為 0，否則費用取決於時間長度，如下所示：

  cost_per_square_hour_after_quadratic_soft_max *
  (duration - quadratic_soft_max_duration)^2

費用必須為非負值。

int64

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

double

如果載重量超過這輛車輛路線的 soft_max_load，系統會依據下列費用懲罰機制收取費用 (每輛車輛只會收取一次)：(載重量 - soft_max_load) * cost_per_unit_above_soft_max。所有費用加總起來，且必須與 Shipment.penalty_cost 使用相同的單位。

Interval

車輛在路線起點的允許載客量間隔。

Interval

車輛在路線結束時可接受的載客量間隔。

int64

可接受的最大負載量。

int64

可接受的最低負載。必須大於或等於 0。如果同時指定這兩個值，min 必須小於或等於 max。

int64

可接受的最大負載。必須大於或等於 0。如果未指定，則此訊息不會限制最大負載。如果同時指定這兩個值，min 必須小於或等於 max。

bool

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

Location

使用地理座標指定的點，包括選用的標頭。

string

與路標相關聯的 POI 地點 ID。