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

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 см. в разделах «Оптимизация стоп-заказов при приеме и доставке» и справочной документации 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
    }
  }
}

Важно: если в сообщениях 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
    }
  }
}