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

Наконец, вот как можно организовать ПУТЕШЕСТВИЕ, ПЕРЕРЫВЫ, ЗАДЕРЖКУ и ОЖИДАНИЕ во время перехода.

  • Они не пересекаются.
  • Значение DELAY уникально и должно охватывать непрерывный период времени непосредственно перед следующим посещением (или окончанием движения транспортного средства). Таким образом, для определения времени начала и окончания задержки достаточно знать её длительность.
  • ПЕРЕРЫВЫ — это непрерывные, неперекрывающиеся периоды времени. В ответе указывается время начала и продолжительность каждого перерыва.
  • 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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
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
}
Поля
vehicleIndex

integer

Транспортное средство, выполняющее маршрут, идентифицируется по его индексу в исходной ShipmentModel .

vehicleLabel

string

Метка транспортного средства, выполняющего этот маршрут, равная ShipmentModel.vehicles(vehicleIndex).label , если указана.

vehicleStartTime

string ( Timestamp format)

Время начала движения транспортного средства по маршруту.

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

vehicleEndTime

string ( Timestamp format)

Время окончания маршрута транспортного средства.

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

visits[]

object ( Visit )

Упорядоченная последовательность посещений, образующая маршрут. visits[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)

Прибытие в пункт назначения next_visit, вероятно, произойдет позже текущего временного окна из-за увеличения предполагаемого времени в пути travelDuration(previous_visit, next_visit) из-за пробок. Кроме того, перерыв может быть вынужденно перекрыт из-за увеличения предполагаемого времени в пути и ограничений временного окна посещения или перерыва.

routePolyline

object ( EncodedPolyline )

Кодированное представление маршрута в виде ломаной линии. Это поле заполняется только в том случае, если OptimizeToursRequest.populate_polylines имеет значение true.

breaks[]

object ( Break )

Перерывы, запланированные для транспортного средства, следующего по этому маршруту. Последовательность breaks представляет собой временные интервалы, каждый из которых начинается в соответствующее startTime и duration в секундах.

metrics

object ( AggregatedMetrics )

Метрики длительности, расстояния и загрузки для этого маршрута. Поля AggregatedMetrics суммируются по всем ShipmentRoute.transitions или ShipmentRoute.visits , в зависимости от контекста.

vehicleFullness

object ( VehicleFullness )

Поле VehicleFullness для вычисления близости ограниченных метрик к соответствующим ограничениям транспортного средства. Его поля представляют собой отношения между полем ограниченной метрики (например, AggregatedMetrics.travel_distance_meters ) и соответствующим ограничением транспортного средства (например, Vehicle.route_distance_limit ).

Экспериментальный: поведение или существование этого поля может измениться в будущем.

routeCosts

map (key: string, value: number)

Стоимость маршрута, разбитая по полям запроса, связанным со стоимостью. Ключами являются прото-пути относительно входного запроса OptimizeToursRequest, например, "model.shipments.pickups.cost", а значениями — общая стоимость, сгенерированная соответствующим полем стоимости, агрегированная по всему маршруту. Другими словами, costs["model.shipments.pickups.cost"] — это сумма всех расходов на забор груза по маршруту. Здесь подробно представлены все расходы, определенные в модели, за исключением расходов, связанных с TransitionAttributes, которые с января 2022 года отображаются только в агрегированном виде.

routeTotalCost

number

Общая стоимость маршрута. Сумма всех расходов в карте стоимости.

Посещать

Посещение, совершённое в ходе маршрута. Этот визит соответствует забору или доставке Shipment .

JSON-представление 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string,
  "injectedSolutionLocationToken": integer
}
Поля
shipmentIndex

integer

Индекс поля shipments в исходной ShipmentModel .

isPickup

boolean

Если значение true, посещение соответствует самовывозу Shipment . В противном случае — доставке.

visitRequestIndex

integer

Индекс VisitRequest в поле самовывоза или доставки Shipment (см. isPickup ).

startTime

string ( Timestamp format)

Время начала визита. Обратите внимание, что транспортное средство может прибыть к месту визита раньше. Время соответствует ShipmentModel .

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

loadDemands

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

Общий спрос на загрузку за посещение рассчитывается как сумма отгрузки и запроса на посещение loadDemands . Значения отрицательные, если посещение является доставкой. Спрос учитывается для тех же типов, что и Transition.loads (см. это поле).

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.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

shipmentLabel

string

Копия соответствующей Shipment.label , если она указана в Shipment .

visitLabel

string

Копия соответствующего VisitRequest.label , если он указан в VisitRequest .

injectedSolutionLocationToken

integer

Непрозрачный токен, представляющий информацию о месте посещения.

Это поле может быть заполнено в результатах посещений маршрутов, если для этого посещения VisitRequest.avoid_u_turns было задано значение true или если ShipmentModel.avoid_u_turns было задано значение true в запросе OptimizeToursRequest .

Экспериментальный вариант: более подробную информацию см. на странице https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request .

Переход

Переход между двумя событиями на маршруте. См. описание ShipmentRoute .

Если у транспортного средства нет startLocation и/или endLocation , соответствующие метрики перемещения равны 0.

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)
    },
    ...
  }
}
Поля
travelDuration

string ( Duration format)

Продолжительность поездки во время этого перехода.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

travelDistanceMeters

number

Расстояние, пройденное за время перехода.

trafficInfoUnavailable

boolean

Когда трафик запрашивается через OptimizeToursRequest.consider_road_traffic и информация о трафике для Transition не может быть получена, это логическое значение принимает значение true. Это может быть временным (редкий сбой в работе серверов трафика в реальном времени) или постоянным (нет данных для этого местоположения).

delayDuration

string ( Duration format)

Сумма длительностей задержек, применяемых к этому переходу. Если задержка есть, она начинается ровно за delayDuration секунд до следующего события (посещения или окончания движения транспортного средства). См. TransitionAttributes.delay .

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

breakDuration

string ( Duration format)

Суммарная продолжительность перерывов, возникающих во время данного перехода, если таковые имеются. Подробная информация о времени начала и продолжительности каждого перерыва хранится в ShipmentRoute.breaks .

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

waitDuration

string ( Duration format)

Время ожидания во время этого перехода. Длительность ожидания соответствует времени простоя и не включает время перерыва. Также обратите внимание, что это время ожидания может быть разделено на несколько несмежных интервалов.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

totalDuration

string ( Duration format)

Общая продолжительность перехода, указанная для удобства, равна:

  • startTime следующего посещения (или vehicleEndTime , если это последний переход) - startTime этого перехода;
  • если ShipmentRoute.has_traffic_infeasibilities имеет значение false, дополнительно выполняется следующее: `totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration`.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

startTime

string ( Timestamp format)

Время начала этого перехода.

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

routePolyline

object ( EncodedPolyline )

Кодированное ломаное представление маршрута, пройденного во время перехода. Это поле заполняется только в том случае, если параметр populateTransitionPolylines имеет значение true.

routeToken

string

Только выходные данные. Непрозрачный токен, который можно передать в Navigation SDK для реконструкции маршрута во время навигации и, в случае изменения маршрута, учитывать исходное намерение при его создании. Относитесь к этому токену как к непрозрачному объекту. Не сравнивайте его значение между запросами, так как оно может измениться, даже если служба возвращает тот же маршрут. Это поле заполняется только в том случае, если для populateTransitionPolylines задано значение true.

vehicleLoads

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

Загрузка транспортного средства во время этого перехода для каждого типа, который либо появляется в Vehicle.load_limits этого транспортного средства, либо имеет ненулевое значение Shipment.load_demands для некоторой перевозки, выполненной на этом маршруте.

Нагрузки, полученные во время первого перехода, являются начальными нагрузками маршрута транспортного средства. Затем, после каждого посещения, loadDemands этого посещения либо прибавляются, либо вычитаются для получения нагрузок следующего перехода в зависимости от того, был ли это выезд с самовывозом или доставкой.

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)

Время начала перерыва.

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

duration

string ( Duration format)

Продолжительность перерыва.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

Заполненность транспортного средства

VehicleFullness — это метрика, которая вычисляет степень заполнения транспортного средства. Каждое поле VehicleFullness принимает значения от 0 до 1 и рассчитывается как отношение поля метрики с ограничением (например, AggregatedMetrics.travel_distance_meters ) к соответствующему ограничению для транспортного средства (например, Vehicle.route_distance_limit ), если оно задано. В противном случае коэффициент заполнения не устанавливается. Если ограничение равно 0, значение поля равно 1. Примечание: если маршрут ограничен транспортными средствами, некоторые исходные коэффициенты заполнения могут превышать 1,0, например, транспортное средство может превысить установленный лимит пробега. В таких случаях мы устанавливаем ограничение на значение 1,0.

JSON-представление 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
Поля
maxFullness

number

Максимальное из всех остальных полей в этом сообщении.

distance

number

Соотношение между AggregatedMetrics.travel_distance_meters и Vehicle.route_distance_limit . Если Vehicle.route_distance_limit не задан, это поле также будет не задано.

travelDuration

number

Соотношение между [AggregatedMetrics.travel_duration_seconds][] и Vehicle.travel_duration_limit . Если Vehicle.travel_duration_limit не задан, это поле также будет не задано.

activeDuration

number

Соотношение между [AggregatedMetrics.total_duration_seconds][] и Vehicle.route_duration_limit . Если Vehicle.route_duration_limit не задан, это поле также будет не задано.

maxLoad

number

Максимальное соотношение между всеми типами [AggregatedMetrics.max_load][] и соответствующими им значениями Vehicle.load_limits . Если все поля Vehicle.load_limits не заданы, это поле также будет не задано.

activeSpan

number

Отношение (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) для заданного транспортного средства. Если знаменатель отсутствует, используется ( ShipmentModel.global_end_time - ShipmentModel.global_start_time ).