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

最後，以下是旅客在過渡期間安排旅遊行程、休息時間、誤點和等待時間的方法。

  • 不會重疊。
  • 延遲是獨一無二的，且必須在下次造訪或車輛終點之前的連續一段時間。因此，您可以從中瞭解延遲時間的開始和結束時間。
  • 中斷期間是連續、不重疊的時間。回應會指定每個廣告插播的開始時間和持續時間。
  • 「旅遊」和「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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
JSON 表示法 
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "metrics": {
    object (AggregatedMetrics)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
欄位
vehicleIndex

integer

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

string

執行這條路線的車輛標籤，等於 ShipmentModel.vehicles(vehicleIndex).label (如有指定)。
vehicleStartTime

string (Timestamp format)

車輛開始行駛的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
vehicleEndTime

string (Timestamp format)

車輛完成路線的時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
visits[]

object (Visit)

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

object (Transition)

路線的轉換已排序清單。
hasTrafficInfeasibilities

boolean

如果將 OptimizeToursRequest.consider_road_traffic 設為 true，這個欄位表示路線時間不一致，是根據路況估算的交通時間來預測。無論是第一次造訪前後、首次造訪前或上次造訪後，時間都可能不足以完成按照車流量調整的交通、延誤和休息時間，但這仍會滿足親臨門市需求和車輛的時效。例如：

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

因為路況的關係，預估的交通時間增加 travelDuration(previous_visit, next_visit)，因此抵達 next_visit 的機率可能會晚於目前的時間範圍。此外，交通時間預估值和造訪/休息時間限制都增加，可能因而迫使休息時間與造訪地點重疊。
routePolyline

object (EncodedPolyline)

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

object (Break)

為行駛這條路線的車輛安排了休息時間。breaks 序列代表時間間隔，每個時間間隔從對應的 startTime 開始，持續 duration 秒。
metrics

object (AggregatedMetrics)

這條路線的時長、距離和載入指標。系統會根據結構定義，為所有 ShipmentRoute.transitions 或 ShipmentRoute.visits 欄位加總 AggregatedMetrics 的欄位。
routeCosts

map (key: string, value: number)

路線費用，按照費用相關要求欄位細分。這些鍵是 proto 路徑，相對於輸入的 OptimizeToursRequest，例如：「model.shipments.pickups.cost」和「模型」的值則為相對應費用欄位產生的總費用，並匯總在整條路線上。換句話說，成本 ["model.shipments.pickups.cost"] 是路線上所有取貨費用的總和。這裡詳細列出模型中定義的所有費用，但 TransitionAttributes 的相關費用除外。這些費用只以 2022 年 1 月的匯總方式呈現。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
routeTotalCost

number

路線的總費用。費用對應中所有費用的總和。

前往

在航線中進行造訪。本次造訪對應的是取貨或送貨 Shipment。

JSON 表示法 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
欄位
shipmentIndex

integer

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

boolean

如果造訪為 true，則造訪對應至 Shipment 的取貨。否則對應項目會對應提交內容。
visitRequestIndex

integer

Shipment 的自取或外送欄位中的 VisitRequest 索引 (請參閱 isPickup)。
startTime

string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
loadDemands

map (key: string, value: object (Load))

總造訪載入需求是出貨總和與造訪要求 loadDemands。如果造訪是運送，這個值會是負值。系統會針對與 Transition.loads 相同的類型回報要求 (請參見這個欄位)。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
detour

string (Duration format)

由於商家抵達前路線上的貨物運送，且所需時間會因此導致的可能等待時間，因此需要額外的往返時間。如果是外送服務，則系統會根據對應的上車地點計算行程，並等於：

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

否則，它是從車輛 startLocation 計算而得，等於：

startTime - vehicleStartTime - travel duration from
the vehicle's `startLocation` to the visit.

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
shipmentLabel

string

對應的 Shipment.label 副本 (如果在 Shipment 中指定)。
visitLabel

string

對應的 VisitRequest.label 副本 (如果在 VisitRequest 中指定)。

轉移

路線上的兩個事件之間轉換。請參閱 ShipmentRoute 的說明。

如果車輛沒有 startLocation 和/或 endLocation，則相應的旅遊指標為 0。

JSON 表示法 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
欄位
travelDuration

string (Duration format)

轉換期間的交通時間。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
travelDistanceMeters

number

在過渡期間移動的距離。
trafficInfoUnavailable

boolean

如果透過 OptimizeToursRequest.consider_road_traffic 要求流量，且無法擷取 Transition 的流量資訊，該布林值會設為 true。這可能是暫時性的 (在即時流量伺服器中短暫出現)，也可能是永久 (沒有這個地點的資料)。
delayDuration

string (Duration format)

套用至這個轉換作業的延遲時間長度總和。如有這種情況，延遲時間剛好是發生下一個事件 (造訪或車輛結束) 的 delayDuration 秒前。查看《TransitionAttributes.delay》。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
breakDuration

string (Duration format)

本次移轉期間的廣告插播時間長度總和 (如果有的話)。每個休息時間的開始時間和時間長度詳細資料會儲存在 ShipmentRoute.breaks 中。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
waitDuration

string (Duration format)

轉換期間的等待時間。等待時間長度對應至閒置時間，且不包含休息時間。另請注意，這個等待時間可能會分成幾個不連續的間隔。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
totalDuration

string (Duration format)

轉換總時間 (為了方便起見)。等於：

  • 下一次造訪 startTime (若這是最後一站轉換，則為 vehicleEndTime) - 此轉場效果的 startTime；
  • 如果 ShipmentRoute.has_traffic_infeasibilities 為 false，則還會包含以下內容：`totalDuration = travelDuration +DelayDuration
  • breakDuration + waitDuration`

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
startTime

string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
routePolyline

object (EncodedPolyline)

轉換期間路徑的編碼折線表示法。只有在 populateTransitionPolylines 設為 True 時，系統才會填入這個欄位。
vehicleLoads

map (key: string, value: object (VehicleLoad))

在此轉場期間，車輛會載入該車輛 Vehicle.load_limits 中顯示的每種類型，或是在這條路線上的部分貨運設有非零 Shipment.load_demands。

第一個轉場期間的載入是車輛路線的起始載入。接著，視該次造訪是自取或外送，每次造訪後，都會將造訪的 loadDemands 相加或減去，以獲得下次轉換的載入。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

EncodedPolyline

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

JSON 表示法 
{
  "points": string
}
欄位
points

string

代表折線已編碼點的字串。

休息時間

代表廣告插播執行的資料。

JSON 表示法 
{
  "startTime": string,
  "duration": string
}
欄位
startTime

string (Timestamp format)

休息的開始時間。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
duration

string (Duration format)

休息時間長度。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。