API оптимизации маршрутов возвращает маршруты для транспортных средств в соответствующем запросе. Отгрузки закрепляются за транспортными средствами или могут быть пропущены в зависимости от свойств запроса.
Сообщение OptimizeToursResponse
( REST , gRPC ) имеет два основных свойства верхнего уровня:
-
routes[]
— это маршруты для каждого транспортного средства с назначенными ему отгрузками. КаждыйRoute
содержит метрики, отражающие свойства этого отдельного маршрута. -
metrics
— это агрегированные показатели для всего ответа, для всех транспортных средств и планов маршрутов. Метрики верхнего уровня содержат те же свойства, что и метрики для каждого маршрута, при этом значения агрегируются по всем маршрутам.
Некоторые свойства могут не всегда заполняться в зависимости от результатов оптимизации:
-
skippedShipments[]
перечисляет поставки, которые не выполняются ни одним транспортным средством. Отгрузка может быть пропущена, если она не может быть выполнена в рамках заданных ограничений или если стоимость выполнения перевозки превышает стоимость штрафа. Например, если получение или доставка груза имеет очень узкийtimeWindow
, для транспортного средства может оказаться невозможным или экономически неэффективным посещение в течение требуемого временного окна. -
validationErrors[]
указывает ошибки, которые делают запрос недействительным или невозможным для решения, когда дляsolvingMode
запроса установлено значениеVALIDATE_ONLY
. В обычном режимеDEFAULT_SOLVE
ошибки проверки отображаются в сообщении об ошибке, а не в теле ответа. Обратите внимание, что режим решенияVALIDATE_ONLY
может сообщать о нескольких ошибках одновременно, что полезно для быстрой отладки запросов.
Свойства маршрута
Каждая запись routes[]
представляет собой сообщение ShipmentRoute
( REST , gRPC ). Каждый ShipmentRoute
представляет назначение маршрута для конкретного транспортного средства из запроса. Важные свойства ShipmentRoute
, относящиеся к соответствующему Vehicle
, включают:
-
vehicleIndex
— это индексVehicle
, начинающийся с нуля, в соответствующем сообщении запроса. В ответах REST это свойство опускается, если его значение равно нулю. -
vehicleStartTime
— время, когда транспортное средство должно начать свой маршрут. -
vehicleEndTime
— это время, когда транспортное средство должно завершить свой маршрут.
В ответе routes
будут выглядеть так:
{
"routes": [
{
"vehicleStartTime": "2024-02-13T00:00:00Z",
"vehicleEndTime": "2024-02-13T00:38:42Z",
"visits": [
...
],
"transitions": [
...
],
"metrics": {
...
},
...
}
],
...
}
Каждый ShipmentRoute
включает упорядоченный список visits
, которые совершит транспортное средство. Каждое Visit
( REST , gRPC ) представляет собой VisitRequest
( REST , gRPC ) из соответствующего запроса. Важные свойства Visit
включают в себя:
-
shipmentIndex
— это нулевой индекс груза, которому принадлежит это посещение в соответствующем запросе. -
isPickup
имеет значение true, когда посещение является самовывозом, и false, когда посещение является доставкой. В ответах REST это свойство опускается, если значение равно false. -
visitRequestIndex
— это отсчитываемый от нуля индексVisitRequest
изShipment.pickups
илиShipment.deliveries
в соответствующем запросе, который представляетVisit
. В ответах REST это свойство опускается, если его значение равно нулю. -
startTime
— ожидаемое время начала посещения. -
loadDemands
сопоставляет тип нагрузки с объемом загрузки, необходимым для завершенияVisit
. Объемы груза для посещений доставки являются отрицательными и представляют собой снятие груза с транспортного средства.
Пример Visit
выглядит так:
{
"routes": [
{
...
"visits": [
{
"isPickup": true,
"startTime": "2024-02-13T00:00:00Z",
"detour": "0s"
},
...
],
},
...
],
...
}
Каждый ShipmentRoute
включает упорядоченный список transitions
, которые представляют собой путешествие между visits
данного транспортного средства. Важные свойства сообщения Transition
( REST , gRPC ) включают в себя:
-
startTime
— время, в которое транспортное средство начнет выполнять переход. -
travelDuration
— это продолжительность, в течение которой транспортное средство должно проехать, чтобы завершить переход. -
travelDistanceMeters
— расстояние в метрах, которое транспортное средство должно преодолеть, чтобы завершить переход. -
trafficInfoUnavailable
указывает, доступны ли данные о трафике для перехода. -
waitDuration
представляет время простоя, которое транспортное средство проводит в ожидании, прежде чем оно сможет начать следующийVisit
. Это может произойти из-заstart_time
следующегоVisit
. -
totalDuration
— общая продолжительность перехода, включая время перемещения, ожидания, перерыва и задержки. -
vehicleLoads
сопоставляет тип груза с количеством груза, перевозимым транспортным средством во время этого перехода.
Пример Transition
выглядит так:
{
"routes": [
{
...
"transitions": [
...
{
"travelDuration": "1171s",
"travelDistanceMeters": 9004,
"waitDuration": "0s",
"totalDuration": "1171s",
"startTime": "2024-02-13T00:00:00Z"
},
...
],
...
}
],
...
}
Взаимосвязь между vists
и transitions
описана в Оптимизация заказов Pickup and Delivery Stop Order , а также в справочной документации ShipmentRoute
( REST , gRPC ).
Свойства метрик
Сообщение Metrics
( REST , gRPC ) суммирует все решение. Некоторые важные свойства Metrics
включают в себя:
-
totalCost
— это общие затраты, понесенные при прохождении маршрутов. Подробнее о затратах читайте в разделе «Параметры модели затрат» . -
usedVehicleCount
— общее количество транспортных средств, использованных в решении. Транспортные средства могут иметь пустые маршруты, когда оптимизатор определяет, что в их использовании нет необходимости. -
skippedMandatoryShipmentCount
— количество пропущенных отправлений, которые являются «обязательными». При обязательной отправке не указываетсяpenaltyCost
, которая начисляется в случае пропуска отгрузки. Обязательные поставки все равно можно пропустить, если их выполнение невозможно при определенных ограничениях. Подробнее о затратах читайте в разделе «Параметры модели затрат» .
Дополнительные метрики передаются в виде сообщений AggregatedMetrics
( REST , gRPC ). Тип сообщения AggregatedMetrics
используется для свойства Metrics.aggregatedRouteMetrics
, а для свойства ShipmentRoute.metrics
Metrics.aggregatedRouteMetrics
содержит метрики, агрегированные по всем ShipmentRoute
в OptimizeToursResponse
. Каждое свойство ShipmentRoute.metrics
содержит метрики для этого конкретного ShipmentRoute
.
Важные свойства AggregatedMetrics
включают:
-
performedShipmentCount
— количество отправлений, выполненных транспортными средствами по всем маршрутам. -
travelDuration
— общее время, которое транспортные средства проводят в пути при прохождении маршрута. -
waitDuration
— общее время, которое транспортные средства проводят в ожидании при прохождении маршрута. -
delayDuration
— общее время задержки транспортных средств. Обычно это значение равно нулю, если в запросе не используютсяTransitionAttributes
. -
breakDuration
— общее время, которое транспортные средства проводят в перерывах при прохождении маршрута. -
visitDuration
— общее время, которое транспортные средства тратят на посещение при прохождении маршрута. По сути, это сумма всех значенийVisitRequest.duration
дляVisitRequest
, соответствующихVisit
, назначенных соответствующему транспортному средству. -
totalDuration
— общая продолжительность, необходимая для прохождения маршрута транспортных средств. -
travelDistanceMeters
— общее расстояние, пройденное транспортными средствами при прохождении маршрута. -
maxLoads
сопоставляет типы грузов с максимальным объемом груза, перевозимым транспортными средствами в любой точке их маршрута.
Пример сообщения Metrics
выглядит так:
{
"routes": [
...
],
"metrics": {
"aggregatedRouteMetrics": {
"performedShipmentCount": 1,
"travelDuration": "2322s",
"waitDuration": "0s",
"delayDuration": "0s",
"breakDuration": "0s",
"visitDuration": "0s",
"totalDuration": "2322s",
"travelDistanceMeters": 18603
},
"usedVehicleCount": 1,
"earliestVehicleStartTime": "2024-02-13T00:00:00Z",
"latestVehicleEndTime": "2024-02-13T00:38:42Z",
"totalCost": 18.603,
"costs": {
"model.vehicles.cost_per_kilometer": 18.603
}
}
}
Полный пример
Полный пример ответа на запрос от Construct a Request выглядит так:
{
"routes": [
{
"vehicleStartTime": "2024-02-13T00:00:00Z",
"vehicleEndTime": "2024-02-13T00:38:42Z",
"visits": [
{
"isPickup": true,
"startTime": "2024-02-13T00:00:00Z",
"detour": "0s"
},
{
"startTime": "2024-02-13T00:19:31Z",
"detour": "0s"
}
],
"transitions": [
{
"travelDuration": "0s",
"waitDuration": "0s",
"totalDuration": "0s",
"startTime": "2024-02-13T00:00:00Z"
},
{
"travelDuration": "1171s",
"travelDistanceMeters": 9004,
"waitDuration": "0s",
"totalDuration": "1171s",
"startTime": "2024-02-13T00:00:00Z"
},
{
"travelDuration": "1151s",
"travelDistanceMeters": 9599,
"waitDuration": "0s",
"totalDuration": "1151s",
"startTime": "2024-02-13T00:19:31Z"
}
],
"metrics": {
"performedShipmentCount": 1,
"travelDuration": "2322s",
"waitDuration": "0s",
"delayDuration": "0s",
"breakDuration": "0s",
"visitDuration": "0s",
"totalDuration": "2322s",
"travelDistanceMeters": 18603
},
"routeCosts": {
"model.vehicles.cost_per_kilometer": 18.603
},
"routeTotalCost": 18.603
}
],
"metrics": {
"aggregatedRouteMetrics": {
"performedShipmentCount": 1,
"travelDuration": "2322s",
"waitDuration": "0s",
"delayDuration": "0s",
"breakDuration": "0s",
"visitDuration": "0s",
"totalDuration": "2322s",
"travelDistanceMeters": 18603
},
"usedVehicleCount": 1,
"earliestVehicleStartTime": "2024-02-13T00:00:00Z",
"latestVehicleEndTime": "2024-02-13T00:38:42Z",
"totalCost": 18.603,
"costs": {
"model.vehicles.cost_per_kilometer": 18.603
}
}
}