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

И наконец, вот как можно организовать поездки, перерывы, задержки и ожидание во время пересадки.

  • Они не пересекаются.
  • Задержка уникальна и должна представлять собой непрерывный период времени непосредственно перед следующим визитом (или окончанием движения транспортного средства). Таким образом, достаточно знать продолжительность задержки, чтобы определить время ее начала и окончания.
  • Перерывы представляют собой смежные, непересекающиеся периоды времени. В ответе указывается время начала и продолжительность каждого перерыва.
  • Путешествие и ожидание являются «прерываемыми»: они могут быть прерваны несколько раз в течение этого переходного периода. Клиенты могут предположить, что путешествие состоится «как можно скорее», а оставшееся время будет заполнено «ожиданием».

Пример (сложный):

                               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)

Прибытие в пункт следующего визита, вероятно, произойдет позже текущего временного окна из-за увеличения расчетного времени в пути 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,
  "visitType": enum (VisitType),
  "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 .

visitType

enum ( VisitType )

Необязательный параметр. Указывает тип визита. Переопределяет поле Visit.is_pickup .

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 .

Тип посещения

Указывает, является ли визит посадкой, доставкой или посещением Stop . Посещения Stop используются только при включенной многомодальной оптимизации.

Перечисления
VISIT_TYPE_UNSPECIFIED Тип визита не указан.
PICKUP_SHIPMENT Визит соответствует получению посылки.
DELIVER_SHIPMENT Визит соответствует доставке груза.

Переход

Переход между двумя событиями на маршруте. См. описание 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 за этот этап либо суммируются, либо вычитаются для получения нагрузок на следующий этап, в зависимости от того, было ли это посещение погрузкой или разгрузкой.

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

Закодированное представление полилинии. Более подробную информацию о кодировании полилиний можно найти здесь: 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 ).