Interpretowanie odpowiedzi

Interfejs Route Optimization API zwraca trasy dla pojazdów w odpowiednim żądaniu. Przesyłki są przypisywane do pojazdów lub mogą być pomijane w zależności od właściwości żądania.

Wiadomość OptimizeToursResponse (REST, gRPC) ma 2 główne właściwości najwyższego poziomu:

• routes[] to trasy każdego pojazdu z przypisanymi przesyłkami. Każdy Route zawiera dane odzwierciedlające właściwości danej trasy.
• metrics to zagregowane wskaźniki dotyczące całej odpowiedzi, obejmujące wszystkie pojazdy i plany tras. Wskaźniki najwyższego poziomu zawierają te same właściwości co wskaźniki dla poszczególnych tras, a wartości są zagregowane dla wszystkich tras.

Niektóre właściwości mogą nie być zawsze wypełniane w zależności od wyników optymalizacji:

1. skippedShipments[] zawiera listę przesyłek, które nie są realizowane przez żaden pojazd. Przesyłkę można pominąć, jeśli nie można jej zrealizować w ramach określonych ograniczeń lub jeśli koszt jej realizacji przekracza koszt kary. Jeśli na przykład odbiór lub dostawa przesyłki ma bardzo krótki czastimeWindow, może się okazać, że nie jest możliwe lub nieopłacalne, aby pojazd wykonał wizytę w wymaganym oknie czasowym.
2. Wartość validationErrors[] określa błędy, które powodują, że żądanie jest nieprawidłowe lub niemożliwe do rozwiązania, gdy parametr solvingMode ma wartość VALIDATE_ONLY. W normalnym trybie DEFAULT_SOLVE błędy weryfikacji będą się wyświetlać w komunikacie o błędzie zamiast w treści odpowiedzi. Pamiętaj, że tryb rozwiązywania VALIDATE_ONLY może zgłosić wiele błędów jednocześnie, co jest przydatne podczas szybkiego debugowania żądań.

Uwaga: aby zinterpretować odpowiedź, musisz mieć odpowiednią prośbę. Odpowiedź zawiera odniesienia do elementów w żądaniu, przez co trudno ją zinterpretować. Niektóre komunikaty, takie jak Shipment i Vehicle, mają właściwości etykiety, które ułatwiają dopasowanie danych żądania i odpowiedzi.

Właściwości trasy

Każdy wpis routes[] to wiadomość ShipmentRoute (REST lub gRPC). Każdy element ShipmentRoute odpowiada przypisanej trasie dla konkretnego pojazdu z żądania. Ważne właściwości ShipmentRoute związane z odpowiadającymi im właściwościami Vehicle:

• vehicleIndex to liczony od zera indeks liczby Vehicle w odpowiednim komunikacie z żądania. Odpowiedzi REST pomijają tę właściwość, gdy jej wartość wynosi 0.
• vehicleStartTime to czas, w którym pojazd musi rozpocząć trasę.
• vehicleEndTime to czas, w którym pojazd ma zakończyć trasę.

W odpowiedzi routes będzie wyglądać tak:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Uwaga: odpowiedzi REST używają reprezentacji JSON protokołu Buffers, która pomija pola, które mają wartość domyślną odpowiedniego typu i nie obsługują pola obecnego. Oznacza to, że właściwości typu integer, takie jak vehicleIndex, są pomijane, gdy ich wartości są równe 0. Zobacz też oficjalną dokumentację mapowania danych JSON w buforze protokołów.

Każdy ShipmentRoute zawiera uporządkowaną listę visits, którą pojazd ma wykonać. Każdy element Visit (REST, gRPC) reprezentuje element VisitRequest(REST, gRPC) z odpowiedniego żądania. Ważne właściwości Visitto:

• shipmentIndex to indeks przesyłki (liczony od 0) w odpowiednim żądaniu.
• isPickup ma wartość true (prawda), gdy wizyta jest uznawana za „odbiór”, a fałsz, gdy wizyta jest dostawą. Odpowiedzi REST pomijają tę właściwość, gdy jej wartość jest równa fałsz.
• visitRequestIndex to indeks VisitRequest z poziomu 0 w Shipment.pickups lub Shipment.deliveries w odpowiednim żądaniu, które reprezentuje Visit. Odpowiedzi REST pomijają tę właściwość, gdy jej wartość jest równa 0.
• startTime to godzina planowanego rozpoczęcia wizyty.
• loadDemands mapuje typ wczytywania, aby wczytać ilość potrzebną do ukończenia zadania Visit. W przypadku wizyt dostawy wartości ładunku są ujemne, co oznacza ładunek usuwany z pojazdu.

Przykładowy element Visit wygląda tak:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Każdy element ShipmentRoute zawiera uporządkowaną listę elementów transitions, które reprezentują przejazdy między elementami visits danego pojazdu. Ważne właściwości wiadomości Transition (REST, gRPC):

• startTime to czas, w którym pojazd rozpocznie wykonywanie przejścia.
• travelDuration to czas, przez który pojazd musi się przemieszczać, aby dokończyć przenoszenie.
• travelDistanceMeters to odległość w metrach, jaką pojazd musi pokonać, aby dokończyć przejście.
• trafficInfoUnavailable wskazuje, czy dane o ruchu są dostępne w przypadku przejścia.
• waitDuration oznacza czas bezczynności pojazdu, który czeka, aż będzie można rozpocząć następną Visit. Może to być spowodowane start_time z tych Visit.
• totalDuration to łączny czas trwania przejścia, w tym czas przejazdu, oczekiwania, przerwy i opóźnienia.
• vehicleLoads mapuje typ ładunku na ilość ładunku przewożonego przez pojazd podczas tego przejścia.

Przykładowa wartość Transition:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

Więcej informacji o związku między vists a transitions znajdziesz w dokumentacji ShipmentRoute (REST, gRPC) dotyczącej optymalizacji zamówień dotyczących odbioru i dostawy. Więcej informacji o właściwościach routePolyline i routeToken komunikatu Transition znajdziesz w artykule o liniach łamanych przejściowych i tokenach trasy.

Właściwości danych

Komunikat Metrics (REST, gRPC) podsumowuje całe rozwiązanie. Niektóre ważne właściwości Metrics to:

• totalCost to łączny koszt przejazdu po trasach. Więcej informacji o kosztach znajdziesz w artykule Parametry modelu kosztu.
• usedVehicleCount to łączna liczba pojazdów używanych w rozwiązaniu. Jeśli optymalizator uzna, że nie ma potrzeby korzystania z tras, mogą one być puste.
• skippedMandatoryShipmentCount to liczba przesyłek pominiętych, które są „obowiązkowe”. Obowiązkowa przesyłka nie określa penaltyCost, które jest naliczane, jeśli jej pominiesz. Wymagania dotyczące przesyłek można pominąć, jeśli ich realizacja nie jest możliwa z powodu określonych ograniczeń. Więcej informacji o kosztach znajdziesz w sekcji Parametry modelu kosztowego.

Dodatkowe dane są raportowane jako wiadomości AggregatedMetrics (REST, gRPC). Właściwość Metrics.aggregatedRouteMetrics jest używana do typu wiadomości AggregatedMetrics, a właściwość Metrics.aggregatedRouteMetrics – do typu wiadomości Metrics.aggregatedRouteMetrics. Właściwość Metrics.aggregatedRouteMetrics zawiera dane zagregowane ze wszystkich ShipmentRoute w usługach OptimizeToursResponse.ShipmentRoute.metrics Każda usługa ShipmentRoute.metrics zawiera dane dotyczące konkretnego ShipmentRoute.

Ważne właściwości AggregatedMetrics:

• performedShipmentCount to liczba przesyłek zrealizowanych przez pojazdy na wszystkich ich trasach.
• travelDuration to łączny czas spędzony przez pojazdy na trasie podczas wykonywania swoich zadań.
• waitDuration to łączny czas oczekiwania pojazdów podczas wykonywania swoich tras.
• delayDuration to całkowity czas opóźnienia dla pojazdów. Zwykle ma ona wartość 0, chyba że w żądaniu użyto parametru TransitionAttributes.
• breakDuration to łączny czas, jaki pojazd poświęca na przerwy podczas pokonywania trasy.
• visitDuration to łączny czas, jaki pojazdy spędzają na wykonywaniu wizyt podczas realizacji swoich tras. Jest to suma wszystkich wartości VisitRequest.duration dla VisitRequest odpowiadających Visit przypisanych do danego pojazdu.
• totalDuration to łączny czas potrzebny na przejechanie trasy przez pojazdy.
• travelDistanceMeters to całkowita odległość pokonana przez pojazdy podczas pokonywania ich tras.
• maxLoads mapuje typy obciążenia na maksymalne obciążenie przenoszone przez pojazdy w dowolnym punkcie na ich trasach.

Przykładowa wiadomość 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
    }
  }
}

Ważne: jeśli wszystkie koszty w wiadomościach Metrics lub ShipmentRoute wynoszą zero, optymalizator prawdopodobnie nie znajdzie optymalnego zamówienia dla ukończenia zadania Visit. Musisz określić co najmniej 1 parametr kosztu, np. Vehicle.costPerKilometer lub globalDurationCostPerHour. W przeciwnym razie optymalizator może zwrócić dowolne rozwiązanie, które spełnia określone ograniczenia.

Pełny przykład

Pełna przykładowa odpowiedź na żądanie z konstruktora żądań:

{
  "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
    }
  }
}