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 dla każdego pojazdu z przypisanymi przesyłkami. Każdy element Route zawiera dane odzwierciedlające właściwości danej trasy.
• metrics to zagregowane dane dotyczące całej odpowiedzi dla wszystkich pojazdów i planów tras. Dane na najwyższym poziomie zawierają te same właściwości co dane na poziomie trasy, a ich 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łka może zostać pominięta, 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ę pojawiać w komunikacie o błędzie zamiast w treści odpowiedzi. Pamiętaj, że tryb rozwiązywania problemów VALIDATE_ONLY może zgłaszać wiele błędów jednocześnie, co jest przydatne do 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 przypisaniu trasy do konkretnego pojazdu z żądania. Ważne właściwości ShipmentRoute związane z odpowiadającymi im właściwościami Vehicle:

• vehicleIndex to indeks Vehicle w odpowiedniej wiadomości z żądaniem, liczony od 0. 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 które 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 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ść prawda, gdy wizyta to odbiór, a fałsz, gdy to dostawa. 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ść wynosi 0.
• startTime to godzina planowanego rozpoczęcia wizyty.
• loadDemands mapuje typ wczytywania na wymaganą ilość danych do wczytania w celu wykonania Visit. W przypadku wizyt dostawy wartości ładunku są ujemne, co oznacza ładunek usuwany z pojazdu.

Przykładowa wartość Visit:

{
  "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 to czas bezczynności pojazdu, który czeka, aż będzie można rozpocząć następny 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 wiadomości Transition znajdziesz w artykule Przejście na polilinie i tokeny trasy.

Właściwości danych

Wiadomość 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 kosztowego.
• 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 pominiętych przesyłek, które są „obowiązkowe”. W przypadku przesyłki obowiązkowej nie określa się penaltyCost, które są ponoszone, jeśli przesyłka zostanie pominięta. 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). Typ wiadomości AggregatedMetrics jest używany w przypadku właściwości Metrics.aggregatedRouteMetrics, a w przypadku właściwości ShipmentRoute.metrics zawiera dane zagregowane ze wszystkich ShipmentRoute w usługach OptimizeToursResponse.Metrics.aggregatedRouteMetrics 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 łączny czas opóźnienia pojazdów. Zwykle jest to 0, chyba że w żądaniu użyto TransitionAttributes.
• breakDuration to łączny czas przerw w trakcie wykonywania przez pojazdy swoich tras.
• 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 łączna odległość pokonana przez pojazdy podczas realizacji tras.
• maxLoads mapuje typy ładunków na maksymalną ilość ładunku przewożonego przez pojazdy w dowolnym punkcie ich trasy.

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 w wiadomościach Metrics lub ShipmentRoute wszystkie koszty są równe 0, optymalizator prawdopodobnie nie znalazł optymalnego zamówienia do wykonania Visit. Należy 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
    }
  }
}