Struktura podstawowa (model dostawy, dostawa i pojazd)

ShipmentModel ma jeden obiekt „shipments” z typem wiadomości „Shipment” i jeden obiekt „vehicles” z typem wiadomości „Vehicle”.

Celem interfejsu Route Optimization API jest planowanie tras dla floty pojazdów, które mają odwiedzić zestaw lokalizacji. Obiekt OptimizeToursRequest opisuje właściwości tych pojazdów i lokalizacji i stanowi główny element treści żądania każdego punktu końcowego.

Struktura podstawowa obiektu OptimizeToursRequest wygląda tak:

W tym dokumencie opisano te typy wiadomości:

  • ShipmentModel: zawiera listę przesyłek, dostępnych pojazdów i innych obiektów, które opisują ich relacje.
  • Shipment: opisuje lokalizacje, które ma odwiedzić pojazd. Mogą one reprezentować rzeczywiste paczki do odbioru i dostawy lub miejsca, w których kierowca wykonuje usługę.
  • Vehicle: określa sposób 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 on zestaw przesyłek, które mogą być realizowane przez zestaw pojazdów, przy uwzględnieniu ograniczeń i minimalizacji łącznych kosztów.

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

Właściwości Opis
shipmentsvehicles Wymagane obiekty zawierające szczegóły jednej lub wielu przesyłek i pojazdów.
globalStartTimeglobalEndTime Wskazuje początek i koniec przedziału czasowego, w którym wszystkie pojazdy muszą zrealizować wszystkie przesyłki. Te właściwości nie są wymagane, ale zalecamy je uwzględniać, ponieważ optymalizator działa najlepiej, gdy przestrzegasz ograniczeń czasowych.

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

ShipmentModel Przykład

W tym przykładzie masz usługę opieki nad psami i zaczynasz tworzyć prośbę. Podczas definiowania przesyłek i pojazdów chcesz najpierw ustawić godziny otwarcia i godzinne koszty operacyjne.

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

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.

Oto przykładowy kod wiadomości ShipmentModel z uwzględnieniem 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ę obiektu przesyłki, która może zostać dostarczona, lub usługę, która może zostać wykonana na trasie.

Real life shipment equals one `Shipment` message, which is contained within a `shipments` object

Jak widać na diagramie:

  • Wiadomość Shipment zawiera wszystkie informacje o rzeczywistej 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. Definicja tych obiektów:

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

W tabeli poniżej opisano różne scenariusze na podstawie konfiguracji pickups i deliveries w wiadomości Shipment.

Scenariusz Opis
Tylko pickups Zakładamy, że tylko odbierasz przesyłkę.
Tylko deliveries Zakładamy, że załadowanie przesyłki zostało już przeprowadzone lub usługa jest świadczona.
Zarówno pickups, jak i deliveries Przypisany pojazd musi najpierw odbirzeć, a następnie dostarczyć przesyłkę. Tylko pojazd, który odebrał przesyłkę, może ją dostarczyć.
Wiele pól pickups lub deliveries Jeśli przesyłka zawiera wiele możliwości dla 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 w Shipment znajdziesz w dokumentacji referencyjnej.

Shipment Przykład

W tym przykładzie masz firmę zajmującą się opieką nad psami, w ramach której odbierasz psy z domów i dostarczasz je do miejsca opieki nad zwierzętami. Chcesz ustawić lokalizację odbioru dwóch psów i ich lokalizację dostawy w firmie:

  • Pierwsza siedziba psa znajduje się w wieży Coit w San Francisco. Współrzędne tej lokalizacji to 37.8024 (szerokość geograficzna) i -122.4058 (długość geograficzna).
  • Drugi pies mieszka w parku South Sunset Playground w San Francisco. Współrzędne tej lokalizacji to szerokość geograficzna 37,7359 i długość geograficzna -122,5011.
  • Twoje psie przedszkole 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.

Oto 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 definiuje strukturę własności pojazdu, który może realizować dostawę na trasie.

Pojazd w rzeczywistości to jeden komunikat „Vehicle”, który jest zawarty w obiekcie „vehicles”.

Jak widać na diagramie:

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

W tabeli poniżej opisaliśmy niektóre istotne właściwości obiektu Vehicle.

Właściwości Opis
startLocationendLocation Lokalizacja początkowa i końcowa pojazdów, które są częścią końcowej zoptymalizowanej trasy. Jeśli nie są zdefiniowane, przyjmuje się domyślnie pierwsze miejsce odbioru przesyłki i ostatnie miejsce dostawy.
costPerHour, costPerKilometer, costPerTraveledHour Parametry kosztów związane z pojazdem. Zalecamy, aby w żądaniu do interfejsu API znajdował się co najmniej 1 parametr cost. Aby dowiedzieć się więcej o kosztach, zapoznaj się z kluczowym pojęciem modelu kosztowego.
startTimeWindowsendTimeWindows Określ przedziały czasu, w których pojazd może poruszać się po trasie. Muszą one mieścić się w okresie globalStartTimeglobalEndTime ustawionym w ShipmentModel. Ta usługa nie jest wymagana, ale zalecamy ją uwzględnić, ponieważ optymalizator działa najlepiej, gdy przestrzegasz ograniczeń czasowych.

Vehicle Przykład

W tym przykładzie masz firmę zajmującą się opieką nad psami i chcesz określić położenie 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 w właściwościach globalStartTime i globalEndTime obiektu ShipmentModel.

W tym przykładzie wartości właściwości Vehicle w żądaniu to:

Właściwość Wartość Opis
startLocation latitude: 37,759773, longitude: -122,427063 współrzędne początkowe trasy Twojego pojazdu. Te dane odpowiadają lokalizacji Twojego psiego żłobka, który znajduje się w parku Mission Dolores w San Francisco.
endLocation latitude: 37,759773, longitude: -122,427063 współrzędne końcowe trasy pojazdu. Te dane odpowiadają lokalizacji Twojego psiego żłobka, który znajduje się w parku Mission Dolores w San Francisco.
costPerHour 27 Ile płacisz kierowcy za prowadzenie pojazdu do psiego żłobka. Płacisz kierowcy 27 USD za godzinę.

Oto przykładowy kod wiadomości Vehicle z uwzględnieniem 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 referencyjnej.

Przykład pełnego żądania

Poniższy przykładowy kod zawiera kompletne żądanie, które łączy przykłady ShipmentModel, ShipmentVehicle pokazane 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"
  }
}