Интерпретируйте ответ

API оптимизации маршрутов возвращает маршруты для транспортных средств в соответствующем запросе. Отгрузки закрепляются за транспортными средствами или могут быть пропущены в зависимости от свойств запроса.

Сообщение OptimizeToursResponse ( REST , gRPC ) имеет два основных свойства верхнего уровня:

• routes[] — это маршруты для каждого транспортного средства с назначенными ему отгрузками. Каждый Route содержит метрики, отражающие свойства этого отдельного маршрута.
• metrics — это агрегированные показатели для всего ответа, для всех транспортных средств и планов маршрутов. Метрики верхнего уровня содержат те же свойства, что и метрики для каждого маршрута, при этом значения агрегируются по всем маршрутам.

Некоторые свойства могут не всегда заполняться в зависимости от результатов оптимизации:

1. skippedShipments[] перечисляет поставки, которые не выполняются ни одним транспортным средством. Отгрузка может быть пропущена, если она не может быть выполнена в рамках заданных ограничений или если стоимость выполнения перевозки превышает стоимость штрафа. Например, если получение или доставка груза имеет очень узкий timeWindow , для транспортного средства может оказаться невозможным или экономически неэффективным посещение в течение требуемого временного окна.
2. validationErrors[] указывает ошибки, которые делают запрос недействительным или невозможным для решения, когда для solvingMode запроса установлено значение VALIDATE_ONLY . В обычном режиме DEFAULT_SOLVE ошибки проверки отображаются в сообщении об ошибке, а не в теле ответа. Обратите внимание, что режим решения VALIDATE_ONLY может сообщать о нескольких ошибках одновременно, что полезно для быстрой отладки запросов.

Примечание: для интерпретации ответа необходим соответствующий запрос. Ответ содержит ссылки на объекты в запросе, что затрудняет интерпретацию ответа самостоятельно. Некоторые сообщения, такие как Shipment и Vehicle имеют свойства меток, позволяющие упростить сопоставление данных запроса и ответа.

Свойства маршрута

Каждая запись 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": {
        ...
      },
      ...
    }
  ],
  ...
}

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

Каждый 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
    }
  }
}

Важно: если в сообщениях Metrics или ShipmentRoute все затраты равны нулю, оптимизатор вряд ли нашел оптимальный заказ для завершения Visit . Должен быть указан хотя бы один параметр стоимости, например Vehicle.costPerKilometer или globalDurationCostPerHour , иначе оптимизатор может вернуть любое решение, удовлетворяющее указанным ограничениям.

Полный пример

Полный пример ответа на запрос от 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
    }
  }
}