ShipmentRoute

Tuyến đường của một chiếc xe 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à thời điểm rời đ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ư chí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 trong 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 số 0.
  • Điểm cuối của xe luôn đứng sau chuyển đổi #n.

Khi phóng to, bạn sẽ thấy những gì xảy 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 đó, bạn chỉ cần biết thời lượng trễ để 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 chèn quảng cáo.
  • 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à "chờ" sẽ chiếm phần 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 của xe 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 mà 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 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 qua 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 lưu lượng truy cập. Có thể không đủ thời gian để hoàn tất chuyến đi đã điều chỉnh theo lưu lượng truy cập, sự chậm 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 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 thời gian nghỉ.
routePolyline

object (EncodedPolyline)

Biểu thị hình nhiều đường đã 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ả phí đến 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 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 tất 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 truy cập 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,
  "visitType": enum (VisitType),
  "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 ghé thăm này tương ứng với lượt đến lấy Shipment. Nếu không, đó là một lượt phân phối.
visitRequestIndex

integer

Chỉ mục của VisitRequest trong trường đến lấy 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 lượt truy cập là tổng của yêu cầu vận chuyển và yêu cầu truy cập loadDemands. Các giá trị này là âm nếu lượt truy cập là lượt giao hàng. 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 giao hàng đã ghé thăm trên tuyến đường trước khi ghé thăm và thời gian chờ tiềm ẩn do khung thời gian. Nếu chuyến thăm là chuyến giao hàng, thì đường vòng sẽ được tính từ chuyến 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.
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).
visitType

enum (VisitType)

Không bắt buộc. Chỉ định loại lượt truy cập. Ghi đè trường Visit.is_pickup.
injectedSolutionLocationToken

integer

Một mã thông báo không công khai đạ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.

VisitType

Cho biết lượt truy cập là lượt đến lấy hàng, lượt giao hàng hay lượt truy cập vào Stop. Các lượt ghé thăm một điểm dừng chỉ được sử dụng khi bạn bật chế độ tối ưu hoá đa phương thức.

Enum
VISIT_TYPE_UNSPECIFIED Loại lượt ghé thăm chưa được chỉ định.
PICKUP_SHIPMENT Lượt ghé thăm tương ứng với một lần đến lấy hàng để vận chuyển.
DELIVER_SHIPMENT Lượt ghé thăm tương ứng với một lần giao hàng.

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ề chuyến đi 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.
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, giá trị boolean này sẽ được đặt thành true. Điều này có thể là tạm thời (hiếm khi xảy ra lỗi trên máy chủ lưu lượng truy cập theo thời gian thực) hoặ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.
breakDuration

string (Duration format)

Tổng thời lượng của các khoảng thời gian nghỉ xảy ra 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 nghỉ được lưu trữ trong ShipmentRoute.breaks.
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 không hoạt động và không bao gồm thời gian nghỉ. Ngoài ra, hãy 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.
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`.
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 tuân thủ ý đị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 xe trong quá trình chuyển đổi này, cho từng 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 ghé thăm, loadDemands của lượt ghé thăm 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 ghé thăm đó là lượt lấy hàng hay lượt giao hàng.

EncodedPolyline

Biểu diễn được mã hoá của một hình 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 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 thời gian nghỉ.

VehicleFullness

VehicleFullness là một chỉ số tính toán mức độ đầy của 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, trường này sẽ đượ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ị về độ đầ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

Giá trị tối đa của tất cả các trường khác trong thông báo 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, 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, 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, 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 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ế.