Wyślij pierwsze żądanie optymalizacji trasy

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Z tego dokumentu dowiesz się, jak wysłać pierwsze żądanie do interfejsu Route Optimization API, korzystając z rzeczywistego scenariusza.

Dla uproszczenia w przykładzie użyto protokołu HTTP i formatu JSON, aby zademonstrować interfejs REST API. W przypadku środowiska produkcyjnego zalecamy jednak używanie gRPC ze względu na jego zalety związane z wydajnością. gRPC wymaga jednak instalacji. Więcej informacji znajdziesz w artykule Biblioteki klienta interfejsu Route Optimization API.

Scenariusz

Mapa San Francisco z pinezkami oznaczającymi Coit Tower, Mission Dolores Park i South Sunset Playground Park

Prowadzisz w San Francisco przedszkole dla psów w godzinach 7:00–19:00. Dziś rano musisz odebrać 2 psy z różnych miejsc w mieście. Obaj właściciele psów podali przedział czasu odbioru między 7:30 a 9:30.

Masz 1 vana i płacisz kierowcy 27 zł za godzinę. Kierowca i bus rozpoczynają dzień w Twoim przedszkolu o 7:00 i muszą wrócić z porannych odbiorów do 12:00, aby zrobić sobie przerwę na lunch.

Dziś jest 13 lutego 2024 r., a kierowca ma do wykonania te zadania:

  • Podnieś berneńskiego psa pasterskiego w pobliżu Coit Tower.
  • Odbierz psa rasy chihuahua w parku South Sunset Playground.
  • Odprowadź oba psy do przedszkola dla psów w Mission Dolores Park.

Musisz wyznaczyć trasę, która zminimalizuje czas spędzony przez psy w furgonetce, a jednocześnie spełni wymagania dotyczące odbioru i wysadzania.

Zanim zaczniesz

Aby uruchomić kod w tym przykładowym scenariuszu, musisz najpierw wykonać instrukcje w artykule Konfigurowanie interfejsu Route Optimization API.

1. Wybierz podejście do optymalizacji trasy

Interfejs Route Optimization API ma kilka metod, które możesz wybrać w zależności od złożoności problemu optymalizacji.

Ponieważ scenariusz dotyczący opieki nad psem jest prosty i nie wymaga wielu informacji, użyj metody blokującej, np. optimizeTours, która szybko zwraca wyniki w przypadku małych żądań. Więcej informacji o metodach interfejsu Route Optimization API znajdziesz w sekcji Synchroniczne i asynchroniczne punkty końcowe.

Aby wysłać żądanie HTTP POST do metody optimizeTours, użyj tego adresu URL:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Musisz też ustawić krótkie czasy oczekiwania i terminy, aby skrócić niepotrzebny czas oczekiwania. W przypadku tego scenariusza z przedszkolem dla psów optymalizator nie potrzebuje dużo czasu na odpowiedź na Twoje żądanie, więc użyj tych ustawień:

  • Ustaw parametr timeout na 2 sekundy.
  • Pozostaw domyślne ustawienia terminu, czyli 60 sekund w przypadku żądań REST.

2. Tworzenie treści wiadomości z żądaniem

Po wybraniu optimizeToursmetody blokowania i określeniu ustawień limitu czasu i terminu musisz utworzyć treść wiadomości z prośbą.

W tym scenariuszu żądanie jest komunikatem OptimizeToursRequest zakodowanym jako JSON w interfejsie API REST.

Aby utworzyć wiadomość z żądaniem, wykonaj te czynności:

  1. Zacznij od podstawowej struktury żądania, która wygląda tak:

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Więcej informacji o strukturze znajdziesz w przewodniku po kluczowych pojęciach w sekcji Podstawowa struktura (ShipmentModel, Shipment i Vehicle).

  2. Określ dostawy. W polu shipments dodaj Shipment wiadomość dla każdego psa, który ma być odebrany i odwieziony rano. W tym miejscu określasz preferowane przez właściciela psa miejsce i godziny odbioru oraz miejsce i godziny, w których można oddać psa do przedszkola.

    1. Dla każdego psa utwórz VisitRequest dla odbioru i kolejny dla dostawy, który w tym scenariuszu jest określany jako odbiór z przedszkola.

      • W przypadku odbioru ustaw arrivalWaypoint w miejscu odbioru psa (Coit Tower w przypadku berneńskiego psa górskiego lub South Sunset Playground Park w przypadku chihuahua), a timeWindows na godzinę odbioru wskazaną przez właściciela (od 7:30 do 9:30).

      • W przypadku dostaw ustaw arrivalWaypoint w przedszkolu i timeWindows na wymagany czas dostawy (od 9:30 do 11:30).

      Więcej informacji o oknach czasowych znajdziesz w artykule Okna czasowe.

    2. W polu label możesz dodać identyfikator każdej przesyłki, np. „bernardyn” i „chihuahua”. Może to pomóc w identyfikacji przesyłek w odpowiedzi.

    Więcej informacji o definiowaniu przesyłek znajdziesz w artykule Przesyłka.

  3. Określ pojazdy W polu vehicles dodaj wiadomość Vehicle dotyczącą jednego busa z przedszkolem jako punktem początkowym i końcowym, kosztu wynagrodzenia kierowcy i godzin pracy busa.

    1. Ustaw startWaypoint i endWaypoint dla furgonetki na lokalizacje początkową i końcową dnia, czyli przedszkole w pobliżu Mission Dolores Park.

    2. Aby zminimalizować koszty operacyjne, musisz określić ograniczenia kosztowe swojej firmy. Ustaw parametr kosztu costPerHour na 27, czyli kwotę, którą płacisz kierowcy za prowadzenie furgonetki do przedszkola dla psów. Więcej informacji o parametrach kosztów znajdziesz w artykule Model kosztów.

    3. Aby mieć pewność, że optymalizator utworzy trasę w godzinach pracy furgonetki, określ startTimeWindows jako dopuszczalny zakres czasu, w którym kierowca może rozpocząć pracę, a endTimeWindows jako dopuszczalny zakres czasu, w którym kierowca musi wrócić do przedszkola. Więcej informacji o oknach czasowych znajdziesz w artykule Okna czasowe.

  4. Ustaw globalne okno czasowe. Globalne okno czasowe to przedział czasu, w którym bus może odbierać i odwozić dzieci do przedszkola w ciągu dnia. W tym przypadku ustaw globalStartTime na 7:00, a globalEndTime na 19:00 na 13 lutego 2024 r. Są to godziny otwarcia Twojego przedszkola dla psów.

3. Wysyłanie żądania

Oto proste żądanie curl oparte na scenariuszu dotyczącym opieki nad psami, które korzysta z metody blokującej optimizeTours.

Zanim wyślesz prośbę, zastąp PROJECT_NUMBER_OR_ID w przykładowym kodzie identyfikatorem projektu Google Cloud.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": 2s,
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

Parametry żądania użyte w żądaniu

W tej tabeli opisujemy parametry żądania użyte w treści żądania w przykładowym scenariuszu. Możesz filtrować zawartość według elementu nadrzędnego lub wyszukiwać tekst.

Rodzic Parametr Typ usługi Opis
OptimizeToursRequest model object (ShipmentModel) To jest główna część Twojej prośby. Jest to pojedynczy obiekt, w którym definiujesz cały problem, w tym wszystkie psy, które musisz odebrać i odwieźć (shipments), oraz furgonetkę w Twojej flocie (vehicles). Możesz go traktować jako kompletny plan problemu, który musisz zoptymalizować.
timeout Czas trwania Ten parametr określa maksymalny czas, przez jaki serwer przetwarza żądanie przed zwróceniem odpowiedzi. Użyj tego parametru, aby skrócić czas oczekiwania. W przypadku małych i szybkich żądań, takich jak w scenariuszu z opieką nad psami, ustaw tę wartość na 2 s.
ShipmentModel shipments[] tablica obiektów (Shipment) Jest to tablica obiektów, z których każdy reprezentuje psa, którego należy odebrać lub odwieźć.
vehicles[] tablica obiektów (Vehicle) Jest to tablica obiektów, z których każdy określa pojazd we flocie. W tym miejscu opisujesz swoje zasoby, np. furgonetkę, która odbiera i dostarcza przesyłki. Aby uzyskać zoptymalizowaną trasę, musisz zdefiniować co najmniej 1 pojazd.
globalStartTime Sygnatura czasowa Jest to najwcześniejszy możliwy czas wystąpienia dowolnego zdarzenia w całym modelu. Ten parametr zawęża problem optymalizacji w czasie, co ma kluczowe znaczenie dla dokładnych obliczeń natężenia ruchu i wyznaczania tras. W przypadku opieki nad psami ustaw najwcześniejszą godzinę, o której kierowca może rozpocząć pracę danego dnia, czyli 7:00 rano 13 lutego 2024 r.
globalEndTime Sygnatura czasowa Jest to najpóźniejszy możliwy czas wystąpienia dowolnego zdarzenia w całym modelu. W przypadku opieki nad psami ustaw tę datę na moment, w którym furgonetka ma zakończyć pracę, czyli 13 lutego 2024 r. o godzinie 19:00.
Shipment pickups[] tablica obiektów (VisitRequest) To lista wszystkich możliwych opcji odbioru przesyłki. Optymalizator wybiera najlepsze rozwiązanie. W przypadku tego scenariusza opieki nad psami podaj lokalizacje odbioru i przedziały czasowe podane przez każdego właściciela dla każdego psa.
deliveries[] tablica obiektów (VisitRequest) To lista wszystkich możliwych opcji nadania przesyłki. Optymalizator wybiera najlepsze rozwiązanie. W przypadku tego scenariusza opieki nad psami podaj lokalizację placówki i przedział czasowy, w którym kierowca musi wrócić na lunch dla każdego psa.
label ciąg znaków Jest to identyfikator konkretnej przesyłki w Twoim żądaniu. W żądaniu możesz podać etykiety, aby ułatwić odczytanie odpowiedzi. W przypadku opieki nad psem użyj opisowego ciągu znaków, np. „Chihuahua”, „Berneński pies pasterski” lub imienia psa, aby dopasować rozwiązanie do danych wejściowych po otrzymaniu odpowiedzi z interfejsu API.
VisitRequest arrivalWaypoint[] object (Waypoint) Jest to lokalizacja konkretnej wizyty na trasie. Możesz to zdefiniować za pomocą współrzędnych geograficznych, identyfikatora miejsca lub nagłówka. W przypadku opieki nad psami ustaw lokalizację podaną przez właściciela dla pickups, a adres przedszkola dla psów dla deliveries.
timeWindows[] tablica obiektów (TimeWindow) Jest to tablica obiektów, które określają ograniczenia czasowe dotyczące odbioru lub dostawy. W tym scenariuszu użyj tego ustawienia, aby określić przedział czasu odbioru każdego psa i dopuszczalny przedział czasu oddania psów do przedszkola.
Vehicle startWaypoint[] object (Waypoint) Jest to lokalizacja początkowa trasy pojazdu określona za pomocą współrzędnych geograficznych lub identyfikatora miejsca. Ten parametr informuje optymalizator, gdzie pojazd musi rozpocząć trasę. Jeśli nie zdefiniujesz tego punktu pośredniego, optymalizator wybierze jako lokalizację początkową jeden z punktów odbioru lub dostawy. W tym scenariuszu dotyczącym opieki nad psami kierowca rozpoczyna dzień w placówce opieki, więc użyj współrzędnych parku Mission Dolores.
endWaypoint[] object (Waypoint) Jest to miejsce docelowe trasy pojazdu określone za pomocą współrzędnych geograficznych lub identyfikatora miejsca. Ten parametr informuje optymalizator, gdzie pojazd musi zakończyć trasę. Jeśli nie zdefiniujesz tego punktu, optymalizator wybierze jeden z punktów odbioru lub dostawy jako koniec trasy. W tym scenariuszu dotyczącym opieki nad psami kierowca musi zakończyć dzień w placówce opieki, więc użyj współrzędnych parku Mission Dolores.
costPerHour liczba Jest to koszt ponoszony za każdą godzinę korzystania z pojazdu, niezależnie od tego, czy jest on w ruchu, czy nie. W tym scenariuszu dotyczącym opieki nad psami użyj tego, aby modelować stawkę godzinową kierowcy.
startTimeWindows[] tablica obiektów (TimeWindow) Jest to dopuszczalne okno czasowe, w którym kierowca może rozpocząć jazdę furgonetką, aby odebrać psy rano.
endTimeWindows[] tablica obiektów (TimeWindow) Jest to dopuszczalny czas, w którym kierowca może zakończyć jazdę furgonetką i zaparkować z powrotem w przedszkolu dla psów.

Dalej

Interpretowanie odpowiedzi