Z tego dokumentu dowiesz się, jak wysłać pierwsze żądanie do interfejsu Route Optimization API na podstawie rzeczywistego scenariusza.
Dla uproszczenia w przykładzie użyto protokołu HTTP i formatu JSON, aby zademonstrować interfejs API REST. W środowisku produkcyjnym zalecamy jednak używanie gRPC ze względu na korzyści związane z wydajnością. gRPC wymaga jednak instalacji. Więcej informacji znajdziesz w artykule Biblioteki klienta Route Optimization API.
Scenariusz
Prowadzisz w San Francisco hotel dla psów, który jest otwarty od 7:00 do 19:00. Dziś rano chcesz odebrać 3 psy z różnych miejsc w mieście i przywieźć je do swojego centrum opieki.
Berneński pies pasterski i chihuahua to stali klienci, którzy zostali umówieni na wizytę w zeszłym tygodniu. Owczarek niemiecki to nowa prośba, która pojawiła się w ostatniej chwili. Chcesz przyjąć owczarka niemieckiego, jeśli to możliwe, ale nie kosztem stałych klientów.
Masz do dyspozycji 1 furgonetkę i płacisz kierowcy 27 USD za godzinę. Kierowca i furgonetka zaczynają dzień w żłobku o 7:00 i muszą wrócić z porannych odbiorów do południa, aby kierowca mógł zrobić sobie przerwę na lunch.
Dzisiaj jest 13 lutego 2024 r. Wszystkie godziny w tym scenariuszu są podane w czasie lokalnym San Francisco, czyli w strefie czasu pacyficznego standardowego (UTC-8) w lutym. Kierowca ma te zadania:
- Odbierz berneńskiego psa pasterskiego w pobliżu Coit Tower. Właściciel poprosił o krótkie okno odbioru między 8:00 a 8:20.
- Odbierz chihuahua z South Sunset Playground Park. Właściciel zaproponował bardziej elastyczne okno odbioru między 7:30 a 9:30.
- Odbierz owczarka niemieckiego w Land's End. Właściciel poprosił też o krótkie okno odbioru między 8:00 a 8:20.
- Zostaw psy w świetlicy w Mission Dolores Park. Żłobek wymaga, aby dzieci były przyprowadzane między 9:30 a 11:30.
Każdy odbiór i odstawienie psa zajmuje 5 minut.
Ponieważ Land's End jest daleko od Coit Tower, a okna odbioru się pokrywają, kierowca nie może zrealizować wszystkich 3 odbiorów. Optymalizator musi wybrać, którego psa pominąć, aby zminimalizować łączny koszt (wynagrodzenie kierowcy i ewentualne kary za pominięcie).
Zanim zaczniesz
Aby uruchomić kod w tym przykładowym scenariuszu, musisz najpierw wykonać instrukcje podane w artykule Konfigurowanie interfejsu Route Optimization API.
1. Wybierz metodę optymalizacji trasy
Interfejs Route Optimization API udostępnia kilka metod, które możesz wybrać w zależności od złożoności problemu optymalizacji.
Ponieważ ten scenariusz dotyczący hotelu dla psów jest niewielkim i prostym żądaniem, użyj metody blokującej, takiej jak optimizeTours, która szybko dostarcza wyniki w przypadku małych żądań. Więcej informacji o punktach końcowych interfejsu Route Optimization API znajdziesz w artykule Wybieranie punktu końcowego.
Użyj tego adresu URL, aby wysłać żądanie POST HTTP do metody optimizeTours:
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
Musisz też ustawić krótki limit czasu i termin, aby skrócić niepotrzebny czas oczekiwania. W przypadku tego scenariusza z hotelem dla psów optymalizator nie potrzebuje dużo czasu na odpowiedź na żądanie, więc użyj tych ustawień:
- Ustaw parametr
timeoutna 2 sekundy. - Pozostaw ustawienia terminu na wartości domyślnej, która wynosi 60 sekund w przypadku żądań REST.
2. Tworzenie treści wiadomości żądania
Po wybraniu metody blokowania optimizeTours i zdefiniowaniu ustawień limitu czasu i terminu następnym krokiem jest utworzenie treści wiadomości żądania.
W tym scenariuszu żądanie jest komunikatem OptimizeToursRequest zakodowanym jako JSON w interfejsie API REST.
Aby utworzyć wiadomość z prośbą, wykonaj te czynności:
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 dotyczących struktury podstawowej (ShipmentModel, Shipment i Vehicle).
Zdefiniuj przesyłki. W polu
shipmentsdodaj wiadomośćShipmentdla każdego psa, którego trzeba odebrać i odwieźć rano. W tym miejscu określisz preferowane przez właściciela psa miejsce i godziny odbioru oraz lokalizację i godziny, w których można zostawić psa w świetlicy.Dla każdego psa utwórz
VisitRequestdla odbioru i kolejny dla dostawy, który w tym scenariuszu jest określany jako dostarczenie do świetlicy.W sekcji odbiorów ustaw
arrivalWaypointna lokalizację odbioru psa (Coit Tower w przypadku berneńskiego psa pasterskiego, South Sunset Playground Park w przypadku chihuahua lub Land's End w przypadku owczarka niemieckiego). UstawtimeWindowsna czas odbioru wskazany przez właściciela (8:00–8:20 dla berneńskiego psa pasterskiego i owczarka niemieckiego oraz 7:30–9:30 dla chihuahua).W przypadku dostaw ustaw
arrivalWaypointna żłobek, atimeWindowsna wymagany czas wysiadki (9:30–11:30).W przypadku wszystkich odbiorów i dostaw ustaw
durationna 5 minut (300s), aby uwzględnić czas potrzebny na załadunek i rozładunek psów.
Więcej informacji o oknach czasowych znajdziesz w sekcji Okna czasowe.
Aby nadać priorytet stałym klientom, ustawiasz
penaltyCostna1000w przypadku berneńskiego psa pasterskiego i chihuahua oraz na100w przypadku owczarka niemieckiego. Po ustawieniu kosztów kar optymalizator może pominąć dowolnego psa, ale najpierw rozważy pominięcie owczarka niemieckiego (który ma niższą karę), jeśli ograniczenia uniemożliwiają wykonanie wszystkich odbiorów.Możesz użyć pola
label, aby dodać identyfikator dla każdej przesyłki, np. „Berneński pies pasterski”, „Chihuahua” i „Owczarek niemiecki”. Może to pomóc w identyfikacji przesyłek w odpowiedzi.
Więcej informacji o definiowaniu przesyłek znajdziesz w artykule Przesyłka.
Zdefiniuj pojazdy. W polu
vehiclesdodaj wiadomośćVehicledotyczącą jednej furgonetki, w której punktem początkowym i końcowym jest żłobek, a także koszt wynagrodzenia kierowcy i godziny otwarcia furgonetki.Ustaw
startWaypointiendWaypointfurgonetki na lokalizacje początkową i końcową dnia, czyli żłobek w pobliżu Mission Dolores Park.Aby zminimalizować koszty operacyjne, musisz określić ograniczenia kosztów swojej firmy. Ustaw parametr kosztu
costPerHourna27, czyli kwotę, którą płacisz kierowcy za prowadzenie furgonetki. Więcej informacji o parametrach kosztów znajdziesz w artykule Model kosztów.Aby mieć pewność, że optymalizator utworzy trasę w godzinach pracy furgonetki, określ okno czasowe pracy pojazdu. To okno określa ograniczenia czasu rozpoczęcia i zakończenia trasy. Definiując tylko połowę każdego przedziału czasu, dajesz optymalizatorowi elastyczność w rozpoczynaniu trasy później lub kończeniu jej wcześniej:
Ustawienie
startTimewstartTimeWindowsna 7:00 oznacza, że kierowca może rozpocząć zmianę najwcześniej o 7:00. Może też zacząć później, jeśli nie ma żadnych odbiorów wczesnym rankiem.Ustawienie
endTimewendTimeWindowsna południe oznacza, że kierowca musi zakończyć zmianę do południa. Mogą też zakończyć zmianę, gdy tylko zrealizują ostatnią dostawę.
Pominięcie drugiej połowy okien minimalizuje czas oczekiwania i objazdu kierowcy. Więcej informacji o przedziałach czasu znajdziesz w artykule Przedziały czasu.
Więcej informacji o definiowaniu pojazdów znajdziesz w artykule Pojazd.
Ustaw globalne okno czasowe. Globalne okno czasowe reprezentuje przedział czasu, w którym furgonetka może odbierać i odwozić dzieci do żłobka w ciągu dnia. W tym scenariuszu ustaw
globalStartTimena 7:00 iglobalEndTimena 19:00 13 lutego 2024 r., czyli godziny otwarcia hotelu dla psów.
3. Wysyłanie żądania
Poniżej znajdziesz proste żądanie curl oparte na scenariuszu hotelu dla psów, które korzysta z blokującej metody optimizeTours.
Zanim wyślesz żądanie, 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-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Bernese mountain dog",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00-08:00",
"endTime": "2024-02-13T09:30:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "Chihuahua",
"penaltyCost": 1000
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.78018,
"longitude": -122.51194
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T08:00:00-08:00",
"endTime": "2024-02-13T08:20:00-08:00"
}
],
"duration": "300s"
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00-08:00",
"endTime": "2024-02-13T11:30:00-08:00"
}
],
"duration": "300s"
}
],
"label": "German shepherd",
"penaltyCost": 100
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.759719,
"longitude": -122.42798
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00-08:00"
}
],
"endTimeWindows": [
{
"endTime": "2024-02-13T12:00:00-08:00"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00-08:00",
"globalEndTime": "2024-02-13T19:00:00-08:00"
}
}
EOM
Parametry żądania użyte w żądaniu
W tabeli poniżej opisano parametry żądania używane w treści żądania w przykładowym scenariuszu. Możesz filtrować zawartość według elementu nadrzędnego lub wyszukiwania tekstowego.
| Ma dzieci | Parametr | Typ usługi | Opis |
|---|---|---|---|
OptimizeToursRequest |
model |
obiekt (ShipmentModel) |
To jest najważniejsza 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ę we flocie (vehicles). Możesz go traktować jako kompletny plan problemu, który chcesz zoptymalizować. |
timeout |
Czas trwania | Ten parametr określa maksymalny czas, przez jaki serwer pracuje nad żądaniem, zanim zwróci odpowiedź. Użyj tego parametru, aby skrócić czas oczekiwania. W przypadku małych i szybkich żądań, takich jak w tym scenariuszu z hotelem dla psów, ustaw tę wartość na 2 s. | |
ShipmentModel |
shipments[] |
tablica obiektów (Shipment) |
Jest to tablica obiektów, w której każdy obiekt reprezentuje psa, którego należy odebrać lub dostarczyć. |
vehicles[] |
tablica obiektów (Vehicle) |
Jest to tablica obiektów, w której każdy obiekt definiuje pojazd we flocie. To tutaj opisujesz swoje zasoby, takie jak furgonetka, 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ń ruchu i tras. W tym scenariuszu dotyczącym hotelu dla psów ustaw najwcześniejszą godzinę, o której kierowca może rozpocząć pracę w danym dniu, czyli 7:00 13 lutego 2024 r. | |
globalEndTime |
Sygnatura czasowa | Jest to najpóźniejszy możliwy czas wystąpienia dowolnego zdarzenia w całym modelu. W tym scenariuszu dotyczącym opieki nad psami ustaw tę wartość na godzinę, o której furgonetka ma zakończyć pracę, czyli 19:00 13 lutego 2024 r. | |
Shipment |
pickups[] |
tablica obiektów (VisitRequest) |
To jest lista wszystkich możliwych opcji odbioru przesyłki. Optymalizator wybiera najlepszy sposób rozwiązania problemu. W przypadku tego scenariusza z hotelem dla psów podaj miejsca odbioru i przedziały czasowe, które każdy właściciel podał dla każdego psa. |
deliveries[] |
tablica obiektów (VisitRequest) |
To jest lista wszystkich możliwych opcji nadania przesyłki. Optymalizator wybiera najlepszy sposób rozwiązania problemu. W przypadku tego scenariusza dotyczącego świetlicy dla psów podaj lokalizację świetlicy i okno czasowe, w którym kierowca musi wrócić na lunch dla każdego psa. | |
label |
tekst | Jest to identyfikator konkretnej dostawy w żądaniu. W żądaniu możesz określić etykiety, aby ułatwić odczytywanie odpowiedzi. W przypadku tego scenariusza z hotelem dla psów użyj opisowego ciągu znaków, takiego jak „Chihuahua”, „Berneński pies pasterski” lub imię psa, aby dopasować rozwiązanie do danych wejściowych, gdy otrzymasz odpowiedź interfejsu API. | |
penaltyCost |
podwójny | Jest to koszt kary naliczany, jeśli optymalizator pominie tę przesyłkę. Domyślnie przesyłki są obowiązkowe – optymalizator priorytetowo traktuje minimalizowanie pominiętych obowiązkowych przesyłek i pomija je tylko wtedy, gdy nie ma innej opcji. Ustawienie kosztu kary pozwala optymalizatorowi pominąć przesyłkę, jeśli jest ona niewykonalna lub zbyt kosztowna, i umożliwia ważenie priorytetów między przesyłkami. W tym scenariuszu ustawiasz wyższy koszt kary (1000) dla stałych klientów (berneńskiego psa pasterskiego i chihuahua) oraz niższy koszt kary (100) dla owczarka niemieckiego, który został zgłoszony w ostatniej chwili. Dzięki temu optymalizator będzie traktować stałych klientów priorytetowo, więc gdy nie będzie mógł zrealizować wszystkich odbiorów, najpierw rozważy pominięcie owczarka niemieckiego. |
|
VisitRequest |
arrivalWaypoint |
obiekt (Waypoint) |
Jest to lokalizacja konkretnej wizyty na trasie. Możesz to zdefiniować, używając współrzędnych szerokości i długości geograficznej, identyfikatora miejsca lub kierunku. W tym scenariuszu dotyczącym hotelu dla psów ustaw tę wartość na lokalizację podaną przez właściciela dla pickups i na adres hotelu dla deliveries. |
timeWindows[] |
tablica obiektów (TimeWindow) |
Jest to tablica obiektów, które określają ograniczenia czasowe odbioru lub dostawy. W tym scenariuszu użyj tego parametru, aby określić przedział czasu na odbiór każdego psa i akceptowalny przedział czasu na odwiezienie psów do świetlicy. | |
duration |
Czas trwania | Ten parametr określa czas trwania wizyty (np. czas załadunku lub rozładunku). W tym scenariuszu ustawiasz 5-minutowy bufor (300s) dla wszystkich odbiorów i dostaw, aby uwzględnić czas potrzebny kierowcy na załadunek i rozładunek psów. |
|
Vehicle |
startWaypoint |
obiekt (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 na trasie, optymalizator wybierze jako lokalizację początkową jeden z punktów odbioru lub dostawy. W tym scenariuszu dotyczącym hotelu dla psów kierowca zaczyna dzień w hotelu, więc użyj współrzędnych Mission Dolores Park. |
endWaypoint |
obiekt (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 na trasie, optymalizator wybierze jeden z punktów odbioru lub dostawy jako koniec trasy. W tym scenariuszu dotyczącym hotelu dla psów, ponieważ kierowca musi zakończyć dzień w hotelu, użyj współrzędnych Mission Dolores Park. | |
costPerHour |
liczba | Jest to koszt ponoszony za każdą godzinę korzystania z pojazdu, niezależnie od tego, czy jest on w ruchu, czy stoi. W tym scenariuszu dotyczącym hotelu dla psów użyj tego parametru do modelowania stawki godzinowej kierowcy. | |
startTimeWindows[] |
tablica obiektów (TimeWindow) |
Jest to akceptowalny przedział czasu, w którym kierowca może rozpocząć zmianę. W tym scenariuszu dotyczącym hotelu dla psów określ startTime jako 7:00, ale pomiń endTime. Dzięki temu optymalizator może opóźnić rozpoczęcie zmiany, jeśli pierwszy odbiór następuje później rano. Pamiętaj, że nawet jeśli nie podasz wartości endTime dla startTimeWindows, czas rozpoczęcia jest domyślnie ograniczony przez endTimeWindows. Pojazd musi rozpocząć trasę przed jej zakończeniem. |
|
endTimeWindows[] |
tablica obiektów (TimeWindow) |
To jest akceptowalny przedział czasu, w którym kierowca może ukończyć trasę.
W tym scenariuszu dotyczącym hotelu dla psów określ endTime jako południe, ale pomiń startTime. Dzięki temu kierowca może wrócić do żłobka natychmiast po ostatnim wysadzeniu dziecka. |