ShipmentRoute

Tuyến đường của một phương tiện có thể được phân tích theo trục thời gian như sau (giả sử có n lượt ghé thăm):

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

Xin lưu ý rằng chúng tôi phân biệt giữa:

  • "sự kiện đúng giờ", chẳng hạn như thời điểm bắt đầu và kết thúc của xe cũng như thời điểm bắt đầu và kết thúc của mỗi lượt ghé thăm (còn gọi là thời điểm đến và đi). Chúng xảy ra vào một giây nhất định.
  • "khoảng thời gian", chẳng hạn như các lượt truy cập và quá trình chuyển đổi giữa các lượt truy cập. Mặc dù đôi khi các khoảng thời gian có thể có thời lượng bằng 0, tức là bắt đầu và kết thúc cùng một giây, nhưng chúng thường có thời lượng dương.

Bất biến:

  • Nếu có n lượt truy cập, thì sẽ có n+1 lượt chuyển đổi.
  • Lượt truy cập luôn được bao quanh bởi một hiệu ứng chuyển đổi trước đó (cùng chỉ mục) và một hiệu ứng chuyển đổi sau đó (chỉ mục + 1).
  • Quá trình khởi động xe luôn đi kèm với quá trình chuyển đổi 0.
  • Điểm cuối của xe luôn đứng sau chuyển cảnh #n.

Khi phóng to, bạn sẽ thấy những gì diễn ra trong một Transition và một 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

Cuối cùng, đây là cách sắp xếp TRAVEL, BREAKS, DELAY và WAIT trong quá trình chuyển đổi.

  • Chúng không trùng lặp.
  • DELAY là duy nhất và phải là một khoảng thời gian liên tục ngay trước lần truy cập tiếp theo (hoặc khi xe kết thúc hành trình). Do đó, chỉ cần biết thời lượng trễ là đủ để biết thời gian bắt đầu và kết thúc của độ trễ.
  • BREAKS là các khoảng thời gian liên tiếp, không trùng lặp. Phản hồi này chỉ định thời gian bắt đầu và thời lượng của mỗi khoảng thời gian quảng cáo chèn.
  • TRAVEL và WAIT là "có thể bị gián đoạn": chúng có thể bị gián đoạn nhiều lần trong quá trình chuyển đổi này. Các ứng dụng có thể giả định rằng chuyến đi diễn ra "sớm nhất có thể" và "thời gian chờ" sẽ lấp đầy thời gian còn lại.

Ví dụ (phức tạp):

                               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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Biểu diễn dưới dạng 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)
  },
  "vehicleFullness": {
    object (VehicleFullness)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Trường
vehicleIndex

integer

Xe thực hiện tuyến đường, được xác định bằng chỉ mục trong ShipmentModel nguồn.
vehicleLabel

string

Nhãn của xe thực hiện tuyến đường này, bằng với ShipmentModel.vehicles(vehicleIndex).label, nếu được chỉ định.
vehicleStartTime

string (Timestamp format)

Thời gian xe bắt đầu hành trình.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

Thời gian mà xe hoàn thành tuyến đường.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

Trình tự có thứ tự của các lượt ghé thăm đại diện cho một tuyến đường. visits[i] là lượt ghé thăm thứ i trong tuyến đường. Nếu trường này trống, thì xe được coi là chưa sử dụng.
transitions[]

object (Transition)

Danh sách các hiệu ứng chuyển cảnh theo thứ tự cho tuyến đường.
hasTrafficInfeasibilities

boolean

Khi OptimizeToursRequest.consider_road_traffic được đặt thành true, trường này cho biết rằng sự không nhất quán về thời gian của tuyến đường được dự đoán bằng cách sử dụng thông tin ước tính về thời gian di chuyển dựa trên tình trạng giao thông. Có thể không đủ thời gian để hoàn thành chuyến đi có điều chỉnh lưu lượng truy cập, thời gian trễ và khoảng thời gian nghỉ giữa các lượt ghé thăm, trước lượt ghé thăm đầu tiên hoặc sau lượt ghé thăm cuối cùng, trong khi vẫn đáp ứng được khung thời gian của lượt ghé thăm và xe. Ví dụ:

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

Thời gian đến tại next_visit có thể sẽ muộn hơn so với khung thời gian hiện tại do thời gian di chuyển ước tính tăng lên travelDuration(previous_visit, next_visit) do tình trạng giao thông. Ngoài ra, thời gian nghỉ có thể bị buộc phải trùng với thời gian ghé thăm do thời gian di chuyển ước tính tăng lên và các hạn chế về khung thời gian ghé thăm hoặc nghỉ ngơi.
routePolyline

object (EncodedPolyline)

Biểu thị hình nhiều đường được mã hoá của tuyến đường. Trường này chỉ được điền sẵn nếu bạn đặt OptimizeToursRequest.populate_polylines thành true.
breaks[]

object (Break)

Thời gian nghỉ được lên lịch cho xe thực hiện tuyến đường này. Trình tự breaks biểu thị các khoảng thời gian, mỗi khoảng thời gian bắt đầu tại startTime tương ứng và kéo dài duration giây.
metrics

object (AggregatedMetrics)

Chỉ số về thời lượng, khoảng cách và tải trọng cho tuyến đường này. Các trường của AggregatedMetrics được cộng trên tất cả ShipmentRoute.transitions hoặc ShipmentRoute.visits, tuỳ thuộc vào bối cảnh.
vehicleFullness

object (VehicleFullness)

trường VehicleFullness để tính toán mức độ gần của các chỉ số bị giới hạn so với giới hạn tương ứng của xe. Các trường của chỉ số này là tỷ lệ giữa một trường chỉ số có giới hạn (ví dụ: AggregatedMetrics.travel_distance_meters) và giới hạn liên quan của xe (ví dụ: Vehicle.route_distance_limit).

Thử nghiệm: Hành vi hoặc sự tồn tại của trường này có thể thay đổi trong tương lai.
routeCosts

map (key: string, value: number)

Chi phí của tuyến đường, được chia nhỏ theo các trường yêu cầu liên quan đến chi phí. Khoá là đường dẫn proto, tương ứng với OptimizeToursRequest đầu vào, ví dụ: "model.shipments.pickups.cost" và giá trị là tổng chi phí do trường chi phí tương ứng tạo ra, được tổng hợp trên toàn bộ tuyến đường. Nói cách khác, costs["model.shipments.pickups.cost"] là tổng của tất cả chi phí lấy hàng trên tuyến đường. Tất cả chi phí được xác định trong mô hình đều được báo cáo chi tiết tại đây, ngoại trừ chi phí liên quan đến TransitionAttributes (Thuộc tính chuyển đổi) chỉ được báo cáo theo cách tổng hợp kể từ ngày 1/1/2022.
routeTotalCost

number

Tổng chi phí của tuyến đường. Tổng của tất cả các chi phí trong bản đồ chi phí.

Truy cập

Một lượt ghé thăm được thực hiện trong một tuyến đường. Lượt ghé thăm này tương ứng với một lượt đến lấy hàng hoặc giao Shipment.

Biểu diễn dưới dạng JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string,
  "injectedSolutionLocationToken": integer
}
Trường
shipmentIndex

integer

Chỉ mục của trường shipments trong nguồn ShipmentModel.
isPickup

boolean

Nếu đúng, lượt truy cập sẽ tương ứng với lượt đến lấy Shipment. Nếu không, nó sẽ tương ứng với một lượt phân phối.
visitRequestIndex

integer

Chỉ mục của VisitRequest trong trường đến lấy hàng hoặc giao hàng của Shipment (xem isPickup).
startTime

string (Timestamp format)

Thời gian bắt đầu lượt truy cập. Xin lưu ý rằng xe có thể đến sớm hơn thời gian này tại vị trí bạn ghé thăm. Thời gian nhất quán với ShipmentModel.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
loadDemands

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

Tổng nhu cầu tải trọng của lượt ghé thăm là tổng của yêu cầu vận chuyển và yêu cầu ghé thăm loadDemands. Các giá trị này là âm nếu lượt truy cập là lượt phân phối. Nhu cầu được báo cáo cho cùng loại với Transition.loads (xem trường này).
detour

string (Duration format)

Thời gian đi đường vòng thêm do các chuyến hàng được ghé thăm trên tuyến đường trước khi ghé thăm và do thời gian chờ tiềm ẩn do khung thời gian gây ra. Nếu lượt ghé thăm là lượt giao hàng, thì đường vòng sẽ được tính từ lượt ghé thăm tương ứng để lấy hàng và bằng:

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

Nếu không, giá trị này sẽ được tính từ startLocation của xe và bằng:

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

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
shipmentLabel

string

Bản sao của Shipment.label tương ứng, nếu được chỉ định trong Shipment.
visitLabel

string

Bản sao của VisitRequest.label tương ứng, nếu được chỉ định trong VisitRequest.
injectedSolutionLocationToken

integer

Một mã thông báo mờ đại diện cho thông tin về vị trí mà người dùng đã ghé thăm.

Trường này có thể được điền sẵn trong các lượt truy cập vào tuyến đường kết quả khi VisitRequest.avoid_u_turns được đặt thành true cho lượt truy cập này hoặc nếu ShipmentModel.avoid_u_turns được đặt thành true trong yêu cầu OptimizeToursRequest.

Thử nghiệm: Xem https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request để biết thêm thông tin chi tiết.

Hiệu ứng chuyển cảnh

Chuyển đổi giữa hai sự kiện trên tuyến đường. Xem nội dung mô tả về ShipmentRoute.

Nếu xe không có startLocation và/hoặc endLocation, thì các chỉ số tương ứng về hành trình sẽ là 0.

Biểu diễn dưới dạng JSON 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "routeToken": string,
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
Trường
travelDuration

string (Duration format)

Thời gian di chuyển trong quá trình chuyển đổi này.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
travelDistanceMeters

number

Quãng đường đã đi trong quá trình chuyển đổi.
trafficInfoUnavailable

boolean

Khi lưu lượng truy cập được yêu cầu thông qua OptimizeToursRequest.consider_road_traffic và không thể truy xuất thông tin lưu lượng truy cập cho Transition, thì giá trị boolean này được đặt thành true. Đây có thể là sự cố tạm thời (sự cố hiếm gặp trong máy chủ lưu lượng truy cập theo thời gian thực) hoặc sự cố vĩnh viễn (không có dữ liệu cho vị trí này).
delayDuration

string (Duration format)

Tổng thời lượng trễ được áp dụng cho hiệu ứng chuyển đổi này. Nếu có, độ trễ sẽ bắt đầu chính xác delayDuration giây trước sự kiện tiếp theo (lượt truy cập hoặc kết thúc chuyến xe). Vui lòng xem TransitionAttributes.delay.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
breakDuration

string (Duration format)

Tổng thời lượng của các khoảng thời gian xuất hiện trong quá trình chuyển đổi này (nếu có). Thông tin chi tiết về thời gian bắt đầu và thời lượng của mỗi khoảng thời gian chèn được lưu trữ trong ShipmentRoute.breaks.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
waitDuration

string (Duration format)

Thời gian chờ trong quá trình chuyển đổi này. Thời gian chờ tương ứng với thời gian rảnh và không bao gồm thời gian nghỉ. Ngoài ra, xin lưu ý rằng thời gian chờ này có thể được chia thành nhiều khoảng thời gian không liên tục.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
totalDuration

string (Duration format)

Tổng thời lượng của hiệu ứng chuyển đổi, được cung cấp để thuận tiện cho bạn. Giá trị này bằng:

  • lần truy cập tiếp theo startTime (hoặc vehicleEndTime nếu đây là quá trình chuyển đổi cuối cùng) – startTime của quá trình chuyển đổi này;
  • nếu ShipmentRoute.has_traffic_infeasibilities là false, thì điều kiện sau cũng được áp dụng: "totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration`.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
startTime

string (Timestamp format)

Thời gian bắt đầu của hiệu ứng chuyển đổi này.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

Biểu thị bằng hình nhiều đường được mã hoá của tuyến đường đã đi trong quá trình chuyển đổi. Trường này chỉ được điền sẵn nếu bạn đặt populateTransitionPolylines thành true.
routeToken

string

Chỉ có đầu ra. Một mã thông báo không công khai có thể được truyền đến Navigation SDK để tạo lại tuyến đường trong quá trình điều hướng và trong trường hợp định tuyến lại, hãy tôn trọng ý định ban đầu khi tuyến đường được tạo. Hãy coi mã thông báo này là một blob mờ. Đừng so sánh giá trị này giữa các yêu cầu vì giá trị này có thể thay đổi ngay cả khi dịch vụ trả về chính xác cùng một tuyến đường. Trường này chỉ được điền sẵn nếu bạn đặt populateTransitionPolylines thành true.
vehicleLoads

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

Tải trọng của xe trong quá trình chuyển đổi này, đối với mỗi loại xuất hiện trong Vehicle.load_limits của xe này hoặc có Shipment.load_demands khác 0 trên một số chuyến hàng được thực hiện trên tuyến đường này.

Tải trong lần chuyển đổi đầu tiên là tải khởi động của tuyến đường xe. Sau đó, sau mỗi lượt truy cập, loadDemands của lượt truy cập sẽ được cộng hoặc trừ để nhận được số lượt tải của lượt chuyển đổi tiếp theo, tuỳ thuộc vào việc lượt truy cập đó là lượt đến lấy hàng hay lượt giao hàng.

EncodedPolyline

Biểu thị được mã hoá của một đường nhiều đường. Bạn có thể xem thêm thông tin về việc mã hoá đường nhiều đoạn tại đây: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Biểu diễn dưới dạng JSON 
{
  "points": string
}
Trường
points

string

Chuỗi biểu thị các điểm được mã hoá của đường nhiều đoạn.

Nghỉ

Dữ liệu biểu thị việc thực thi một điểm ngắt.

Biểu diễn dưới dạng JSON 
{
  "startTime": string,
  "duration": string
}
Trường
startTime

string (Timestamp format)

Thời gian bắt đầu của một khoảng thời gian nghỉ.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

Thời lượng của một khoảng nghỉ.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".

VehicleFullness

VehicleFullness là một chỉ số tính toán mức độ đầy của một chiếc xe. Mỗi trường VehicleFullness có giá trị từ 0 đến 1, được tính là tỷ lệ giữa một trường chỉ số có giới hạn (ví dụ: AggregatedMetrics.travel_distance_meters) và giới hạn liên quan của xe (ví dụ: Vehicle.route_distance_limit), nếu có. Nếu không, tỷ lệ đầy sẽ không được đặt. Nếu giới hạn là 0, thì trường này được đặt thành 1. Lưu ý: khi một tuyến đường không thể đi qua do tình trạng giao thông, một số tỷ lệ đầy thô có thể vượt quá 1,0, ví dụ: xe có thể vượt quá giới hạn khoảng cách. Trong những trường hợp này, chúng tôi giới hạn giá trị độ đầy ở mức 1.0.

Biểu diễn dưới dạng JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Trường
maxFullness

number

Tối đa cho tất cả các trường khác trong thư này.
distance

number

Tỷ lệ giữa AggregatedMetrics.travel_distance_meters và Vehicle.route_distance_limit. Nếu bạn không đặt Vehicle.route_distance_limit, thì trường này sẽ không được đặt.
travelDuration

number

Tỷ lệ giữa [AggregatedMetrics.travel_duration_seconds][] và Vehicle.travel_duration_limit. Nếu bạn không đặt Vehicle.travel_duration_limit, thì trường này sẽ không được đặt.
activeDuration

number

Tỷ lệ giữa [AggregatedMetrics.total_duration_seconds][] và Vehicle.route_duration_limit. Nếu bạn không đặt Vehicle.route_duration_limit, thì trường này sẽ không được đặt.
maxLoad

number

Tỷ lệ tối đa trong số tất cả các loại [AggregatedMetrics.max_load][] và Vehicle.load_limits tương ứng của chúng. Nếu bạn huỷ thiết lập tất cả các trường Vehicle.load_limits, thì trường này cũng sẽ bị huỷ thiết lập.
activeSpan

number

Tỷ lệ (vehicleEndTime – vehicleStartTime) / (latestVehicleEndTime – earliestVehicleStartTime) cho một chiếc xe cụ thể. Nếu không có mẫu số, hệ thống sẽ dùng (ShipmentModel.global_end_time – ShipmentModel.global_start_time) để thay thế.