Struktura podstawowa (model dostawy, dostawa i pojazd)

Interfejs Route Optimization API służy do planowania tras dla floty pojazdów, które mają odwiedzić zestaw lokalizacji. Obiekt OptimizeToursRequest opisuje właściwości tych pojazdów i lokalizacji i jest podstawową strukturą treści żądania każdego punktu końcowego.

Podstawowa struktura obiektu OptimizeToursRequest jest taka:

• Pole model zawiera komunikat ShipmentModel, który zawiera 2 kluczowe pola:
  • Jedno pole shipments, które zawiera co najmniej jedną wiadomość Shipment.
  • Jedno pole vehicles, które zawiera co najmniej jedną wiadomość Vehicle.

W tym dokumencie opisujemy te typy wiadomości:

• ShipmentModel: zawiera listę przesyłek, dostępnych pojazdów i innych obiektów opisujących ich relacje.
• Shipment: opisuje miejsca, które ma odwiedzić pojazd. Mogą one reprezentować rzeczywiste paczki do odbioru i dostawy lub miejsca, w których kierowca pojazdu świadczy usługę.
• Vehicle: opisuje środek transportu między lokalizacjami przesyłki. Każdy pojazd odpowiada rzeczywistemu pojazdowi lub osobie poruszającej się pieszo.

ShipmentModel

ShipmentModel zawiera elementy problemu optymalizacji trasy. Zawiera zestaw przesyłek, które mogą być realizowane przez zestaw pojazdów, z uwzględnieniem ograniczeń i minimalizacją ogólnych kosztów.

W tabeli poniżej opisujemy niektóre istotne właściwości elementu ShipmentModel:

Właściwości	Opis
shipments i vehicles	Wymagane obiekty zawierające szczegóły dotyczące przesyłek i pojazdów.
globalStartTime i globalEndTime	Wskazuje początek i koniec przedziału czasu, w którym wszystkie pojazdy muszą zrealizować wszystkie dostawy. Chociaż te właściwości nie są wymagane, zalecamy ich uwzględnienie, ponieważ optymalizator działa najlepiej, gdy przestrzega ograniczeń czasowych.

Pełną listę właściwości znajdziesz w dokumentacji referencyjnej dotyczącej ShipmentModel.

ShipmentModel Przykład

W tym przykładzie masz usługę opieki nad psami i zaczynasz tworzyć prośbę. Dostawy i pojazdy zdefiniujesz później, ale chcesz zacząć od ustawienia godzin pracy i godzinowego kosztu operacyjnego.

W tym przykładzie wartości właściwości ShipmentModel w Twoim żądaniu są następujące:

Właściwość	Wartość	Opis
globalStartTime	2024-02-13T00:00:00.000Z	Data i godzina rozpoczęcia godzin pracy.
globalEndTime	2024-02-14T06:00:00.000Z	Data i godzina zakończenia godzin pracy.

Poniżej znajdziesz przykładowy kod wiadomości ShipmentModel zawierający wartości z przykładowego scenariusza.

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

Typ wiadomości Shipment definiuje strukturę właściwości przesyłki, którą można dostarczyć, lub usługi, którą można wykonać na trasie.

Jak widać na diagramie:

• Wiadomość Shipment zawiera wszystkie informacje o prawdziwej przesyłce lub usłudze.
• Wszystkie wiadomości Shipment są określone w polu shipments.
• Pole shipments zawiera co najmniej 1 wiadomość Shipment.

Wiadomość Shipment wymaga co najmniej jednego obiektu pickups lub deliveries. Definicje tych obiektów są następujące:

• pickups określa miejsce odbioru przesyłki.
• deliveries określa lokalizację dostawy przesyłki.
• Zarówno pickups, jak i deliveries zawierają typ wiadomości VisitRequest, który określa lokalizacje i inne szczegóły.

W tabeli poniżej opisano różne scenariusze w zależności od konfiguracji parametrów pickups i deliveries w wiadomości Shipment.

Scenariusz	Opis
Tylko pickups	Zakładamy, że tylko odbierasz przesyłkę.
Tylko deliveries	Zakładamy, że przesyłka została wstępnie załadowana lub świadczysz usługę.
Zarówno pickups, jak i deliveries	Przypisany pojazd musi najpierw odebrać przesyłkę, a potem ją dostarczyć. Dostawę może zrealizować tylko pojazd, który odebrał przesyłkę.
Wiele pól pickups lub deliveries	Jeśli w przypadku dostawy podano kilka możliwości pickups lub deliveries, optymalizator wybiera jedną opcję odbioru i jedną opcję dostawy, aby zminimalizować koszty i spełnić ograniczenia.

Pełną listę właściwości znajdziesz w dokumentacji referencyjnej dotyczącej Shipment.

Shipment Przykład

W tym przykładzie prowadzisz dzienną opiekę nad psami, w ramach której odbierasz psy z domu i dostarczasz je do swojego ośrodka. Chcesz ustawić miejsce odbioru 2 psów i miejsce dostawy w swojej firmie:

• Pierwszy pies mieszka w Coit Tower w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37.8024 i długość geograficzna -122.4058.
• Drugi dom psa znajduje się w parku South Sunset Playground w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37,7359 i długość geograficzna -122,5011.
• Twój żłobek dla psów znajduje się w parku Mission Dolores w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37,759773 i długość geograficzna -122,427063.

Poniżej znajdziesz przykładowy kod wiadomości Shipment, w której obiekt shipments zawiera 2 typy wiadomości Shipment z przykładowymi współrzędnymi.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

Typ wiadomości Vehicle określa strukturę właściwości pojazdu, który może realizować dostawę na trasie.

Jak widać na diagramie:

• Wiadomość Vehicle zawiera wszystkie informacje o prawdziwym pojeździe.
• Wszystkie wiadomości Vehicle są określone w polu vehicles.
• Pole vehicles zawiera wiele wiadomości Vehicle.

W tabeli poniżej opisujemy niektóre właściwości elementu Vehicle.

Właściwości	Opis
startLocation i endLocation	Lokalizacja początkowa i końcowa pojazdów, które są częścią ostatecznej zoptymalizowanej trasy. Jeśli nie są zdefiniowane, domyślnie są to lokalizacje pierwszego odbioru i ostatniej dostawy przesyłki.
costPerHour, costPerKilometer, costPerTraveledHour	Parametry kosztów dotyczące pojazdu. Aby interfejs API zwracał zoptymalizowaną trasę, zalecamy uwzględnienie w żądaniu co najmniej jednego parametru kosztu. Więcej informacji o kosztach znajdziesz w sekcji Model kosztów.
startTimeWindows i endTimeWindows	Określ przedziały czasu, w których pojazd może poruszać się po danej trasie. Muszą one mieścić się w przedziale czasu od globalStartTime do globalEndTime ustawionym w ShipmentModel. Ta właściwość nie jest wymagana, ale zalecamy jej uwzględnienie, ponieważ optymalizator działa najlepiej, gdy przestrzega ograniczeń czasowych.

Vehicle Przykład

W tym przykładzie masz usługę opieki nad psami i chcesz określić lokalizację pojazdu na początku i na końcu dnia oraz ilość zużytego paliwa. Nie musisz określać godzin pracy pojazdu, ponieważ są one zgodne z godzinami zdefiniowanymi we właściwościach globalStartTime i globalEndTime w obiekcie ShipmentModel.

W tym przykładzie wartości właściwości Vehicle w Twoim żądaniu są następujące:

Właściwość	Wartość	Opis
startLocation	latitude: 37.759773, longitude: -122.427063	Współrzędne początkowe trasy pojazdu. Odpowiadają one lokalizacji Twojego przedszkola dla psów, które znajduje się w parku Mission Dolores w San Francisco.
endLocation	latitude: 37.759773, longitude: -122.427063	Współrzędne końca trasy pojazdu. Odpowiadają one lokalizacji Twojego przedszkola dla psów, które znajduje się w parku Mission Dolores w San Francisco.
costPerHour	27	Ile płacisz kierowcy za prowadzenie pojazdu Twojego przedszkola dla psów. Płacisz kierowcy 27 zł za godzinę.

Poniżej znajdziesz przykładowy kod wiadomości Vehicle zawierający wartości z przykładowego scenariusza.

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

Pełną listę właściwości znajdziesz w dokumentacji referencyjnej dotyczącej Vehicle.

Przykład pełnego żądania

Poniższy przykładowy kod zawiera pełny przykład żądania, który łączy przykłady ShipmentModel, Shipment i Vehicle przedstawione w tym dokumencie.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}