Route Optimization 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, если он доставляется. Если значение этого свойства – false, оно не включается в ответы REST.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 можно найти в статье Оптимизация порядка остановок для получения и доставки и справочной документации по ShipmentRoute (REST, gRPC). Подробную информацию о свойствах routePolyline и routeToken сообщения Transition можно найти в статье Переход на полилинии и токены маршрутов.
Свойства показателей
Сообщение 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
}
}
}
Полный пример
Полный пример ответа на запрос из раздела Создание запроса выглядит следующим образом:
{
"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
}
}
}