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

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

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

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

Если это правда, посещение соответствует получению 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 или если в запросе OptimizeToursRequest ShipmentModel.avoid_u_turns было установлено значение true.

Экспериментальный вариант: дополнительные сведения см. на странице 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 +layDuration
  • 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 посещения либо добавляются, либо вычитаются, чтобы получить нагрузки следующего перехода, в зависимости от того, было ли посещение самовывозом или доставкой.

Закодированнаяполилиния

Закодированное представление ломаной линии. Дополнительную информацию о кодировании полилиний можно найти здесь: 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_секунды][] и Vehicle.travel_duration_limit . Если Vehicle.travel_duration_limit не задан, это поле будет не установлено.

activeDuration

number

Соотношение между [AggregatedMetrics.total_duration_секундs][] и Vehicle.route_duration_limit . Если Vehicle.route_duration_limit не установлен, это поле будет отключено.

maxLoad

number

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

activeSpan

number

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