Struktura podstawowa (model dostawy, dostawa i pojazd)

ShipmentModel ma 1 obiekt `shipments` z typem wiadomości `Shipment` i 1 obiekt `vehicles` z typem wiadomości `Vehicle`.

Celem interfejsu Route Optimization API jest planowanie tras dla floty pojazdów, które mają odwiedzić określony 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:

Ten dokument opisuje te typy wiadomości:

  • ShipmentModel: zawiera listę dostaw, dostępnych pojazdów i innych obiektów, które opisują ich relacje.
  • Shipment: opisuje lokalizacje, które mają zostać odwiedzone przez pojazd. Mogą one reprezentować rzeczywiste paczki do odebrania i dostarczenia lub miejsca, w których kierowca pojazdu świadczy usługę.
  • Vehicle: opisuje środek transportu między lokalizacjami dostawy. Każdy pojazd odpowiada rzeczywistemu pojazdowi lub osobie poruszającej się pieszo.

ShipmentModel

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

W tabeli poniżej znajdziesz opis niektórych istotnych właściwości ShipmentModel:

Właściwości Opis
shipments i vehicles Wymagane obiekty, które zawierają szczegóły dotyczące jednej lub wielu dostaw i pojazdów.
globalStartTime i globalEndTime Wskazuje początek i koniec okna czasowego , 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 w ShipmentModel znajdziesz w dokumentacji.

Przykład ShipmentModel

W tym przykładzie masz usługę opieki nad psami i zaczynasz tworzyć żądanie. Dostawy i pojazdy zdefiniujesz później, ale na początek chcesz ustawić godziny otwarcia i godzinowy koszt operacyjny.

W tym przykładzie wartości właściwości ShipmentModel w żądaniu są takie:

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

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 dostawy, która może zostać zrealizowana, lub usługi, która może zostać wykonana na trasie.

Rzeczywista dostawa odpowiada jednej wiadomości `Shipment`, która jest zawarta w obiekcie `shipments`.

Jak widać na diagramie:

  • Wiadomość Shipment zawiera wszystkie informacje o rzeczywistej dostawie lub usłudze.
  • Wszystkie Shipment wiadomości są określone w polu shipments.
  • Pole shipments zawiera jedną lub wiele wiadomości Shipment.

Wiadomość Shipment wymaga co najmniej 1 obiektu pickups lub deliveries. Definicje tych obiektów są takie:

W tabeli poniżej znajdziesz opis różnych scenariuszy na podstawie konfiguracji pickups i deliveries w wiadomości Shipment.

Scenariusz Opis
Tylko pickups Zakładamy, że tylko odbierasz dostawę.
Tylko deliveries Zakładamy, że dostawa została już załadowana lub świadczysz usługę.
Zarówno pickups, jak i deliveries Przypisany pojazd musi najpierw odebrać, a potem dostarczyć przesyłkę. Dostawę może zrealizować tylko pojazd, który odebrał przesyłkę.
Wiele pickups lub deliveries Jeśli dostawa zawiera kilka możliwości pickups lub deliveries, optymalizator wybiera 1 opcję odbioru i 1 opcję dostawy na podstawie minimalizacji kosztów i spełnienia ograniczeń.

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

Przykład Shipment

W tym przykładzie masz usługę opieki nad psami, w ramach której odbierasz psy z ich domów i dostarczasz je do swojego przedszkola. Chcesz ustawić lokalizację odbioru 2 psów i ustawić lokalizację dostawy w swojej firmie:

  • Dom pierwszego psa znajduje się w Coit Tower w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37.8024 i długość geograficzna -122.4058.
  • Dom drugiego psa znajduje się w South Sunset Playground Park w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37.7359 i długość geograficzna -122.5011.
  • Twoje przedszkole dla psów znajduje się w Mission Dolores Park 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 Shipmentz 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 definiuje strukturę właściwości pojazdu, który może zrealizować dostawę na trasie.

Pojazd w rzeczywistości odpowiada jednemu komunikatowi `Vehicle`, który jest zawarty w obiekcie `vehicles`.

Jak widać na diagramie:

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

W tabeli poniżej znajdziesz opis niektórych istotnych właściwości 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 odbioru pierwszej dostawy i dostawy ostatniej.
costPerHour, costPerKilometer, costPerTraveledHour Parametry kosztów specyficzne dla pojazdu. Aby interfejs API zwrócił zoptymalizowaną trasę, zalecamy podanie w żądaniu co najmniej 1 parametru kosztu. Więcej informacji o kosztach znajdziesz w artykule Kluczowe pojęcia dotyczące modelu kosztów.
startTimeWindows i endTimeWindows Określ okresy , w których pojazd może poruszać się po trasie. Muszą one mieścić się w oknie czasowym globalStartTime i globalEndTime ustawionym w ShipmentModel. Chociaż ta właściwość nie jest wymagana, zalecamy jej uwzględnienie , ponieważ optymalizator działa najlepiej, gdy przestrzega ograniczeń czasowych.

Przykład Vehicle

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 żądaniu są takie:

Właściwość Wartość Opis
startLocation latitude: 37.759773, longitude: -122.427063 Współrzędne początkowe trasy pojazdu. Są one zgodne z lokalizacją Twojego przedszkola dla psów, które znajduje się w Mission Dolores Park w San Francisco.
endLocation latitude: 37.759773, longitude: -122.427063 Współrzędne końcowe trasy pojazdu. Są one zgodne z lokalizacją Twojego przedszkola dla psów, które znajduje się w Mission Dolores Park w San Francisco.
costPerHour 27 Kwota, którą płacisz kierowcy za prowadzenie pojazdu przedszkola dla psów. Płacisz kierowcy 27 dolarów 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 w Vehicle znajdziesz w dokumentacji.

Pełny przykład żą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"
  }
}