Modeluj działania floty dla pierwszej i ostatniej mili dostaw za pomocą interfejsu Fleet Engine Deliveries API. Możesz użyć tego interfejsu API za pomocą pakietu Driver SDK na Androida lub iOS albo bezpośrednio za pomocą wywołań HTTP REST lub gRPC.
Konfiguracja początkowa
Interfejs Fleet Engine Deliveries API konfigurujesz w konsoli Google Cloud.
Więcej informacji o czynnościach, które należy wykonać w konsoli, i o tym, jak utworzyć token sieciowy JSON na potrzeby autoryzacji, znajdziesz w opisie uwierzytelniania i autoryzacji.
Więcej informacji o korzystaniu z konsoli znajdziesz w dokumentacji Google Cloud Console.
Sprawdzanie konfiguracji
Po utworzeniu kont usługi sprawdź, czy konfiguracja została zakończona, i możesz utworzyć pojazd dostawczy. Od razu sprawdzisz konfigurację, aby mieć pewność, że udało Ci się rozwiązać typowe problemy z autoryzacją, które mogą się pojawić podczas konfigurowania projektu. Konfigurację możesz sprawdzić na 2 sposoby:
Przetestuj 2 kluczowe elementy konfiguracji: podpisywanie tokenów autoryzacji i tworzenie pojazdów w okresie próbnym za pomocą narzędzia wiersza poleceń
gcloud. Szczegółowe informacje znajdziesz w przewodniku po weryfikowaniu konfiguracji.Przetestuj konfigurację za pomocą przykładowych skryptów uwierzytelniania Fleet Engine.
Biblioteki klienta
Aby zwiększyć wygodę programistów w porównaniu z nieprzetworzonym gRPC lub REST, użyj bibliotek klienta w kilku popularnych językach programowania. Instrukcje dotyczące uzyskiwania bibliotek klienta dla aplikacji serwera znajdziesz w artykule o bibliotekach klienta.
W przykładach w języku Java w tej dokumentacji założono, że znasz już gRPC.
Struktury danych
Interfejs Fleet Engine Deliveries API wykorzystuje 2 struktury danych, aby modelować odbiór i dostawę przesyłek:
- Pojazd służący do transportu przesyłki.
- Zadania dotyczące odbioru i dostawy przesyłki.
Korzystasz też z zadań, aby modelować przerwy kierowcy i zaplanowane przystanki na cały dzień.
Pojazdy dostawcze
Pojazdy dostawcze przenoszą przesyłki z depozytu do miejsca dostawy oraz z miejsca odbioru do magazynu. W niektórych przypadkach może też transportować przesyłkę bezpośrednio z miejsca odbioru do miejsca dostawy.
Użyj pakietu Driver SDK, aby utworzyć obiekt DeliveryVehicle we Fleet Engine i wysyłać aktualizacje lokalizacji na potrzeby śledzenia przesyłek i floty.
DeliveryVehicle możesz przypisać maksymalnie 500 zadań i 300 pozostałych segmentów przejazdu pojazdu.
Zadania
Do działań wykonywanych przez pojazd w ciągu dnia przypisujesz zadania według typu działania:
- W przypadku odbioru i dostaw przypisz zadania dostawy.
- Jeśli kierowcy są niedostępni, na przykład gdy wymagane są przerwy, przypisz zadania związane z niedostępnością.
- W przypadku zadań, które nie są wysyłane automatycznie w przypadku skrzynek pocztowych lub lokalizacji klientów, przypisz zaplanowane zadania zatrzymania.
Każde przypisane przez Ciebie zadanie musi mieć unikalny identyfikator zadania, ale zadania mogą mieć ten sam identyfikator śledzenia. Gdy Fleet Engine oblicza okresy szacowanego czasu dotarcia dla każdego zadania, używa wszystkich zadań oraz kolejności ich wykonywania. Więcej informacji o identyfikatorach zadań znajdziesz w wytycznych dotyczących identyfikatorów zadań.
Aby utworzyć zadania we Fleet Engine, użyj menedżera zadań pakietu Driver SDK.
Zadania związane z dostawą
Utwórz zadania dotyczące dostawy obejmujące odbiór i dostawę przesyłki i podaj te informacje:
- Lokalizacja miejsca odbioru lub dostawy.
- Numer śledzenia lub identyfikator.
- Przez określony czas w takim przypadku należy uwzględnić dodatkowy czas na wykonanie zadania, zaparkowanie lub dojście do miejsca przekazania urządzenia.
- Unikalny identyfikator zadania. Zobacz wytyczne dotyczące identyfikatorów zadań.
Więcej informacji można znaleźć w następujących tematach:
Android,
iOS
Zadania związane z niedostępnością
Zadania związane z niedostępnością obejmują okresy, w których pojazd nie jest dostępny do odbioru lub dostawy, np. przerwy na zatankowanie pojazdu lub przerwy na odpoczynek kierowcy.
Utwórz zadanie dotyczące niedostępności zawierające te informacje:
- Czas trwania przerwy.
- Opcjonalnie miejsce przerwy. Nie musisz podawać konkretnej lokalizacji, ale zapewnia to dokładniejsze informacje o szacowanym czasie dotarcia w ciągu dnia.
Więcej informacji można znaleźć w następujących tematach:
Android,
iOS
Zaplanowane zadania zatrzymania
Twórz zadania zaplanowanego zatrzymania, które pozwalają zaplanować postoje, które musi wykonać pojazd dostawczy. Możesz na przykład utworzyć zadanie zaplanowanego zatrzymania dla codziennie zaplanowanego przystanku odbioru w określonej lokalizacji, niezależnie od innych dostaw lub odbiorów w tym samym miejscu. Możesz też tworzyć zaplanowane zadania zatrzymania obejmujące zbiór ze skrytek pocztowych lub modelowanie przesyłek w pojazdach dostawczych lub postojów w centrach obsługi i punktach obsługi.
Więcej informacji można znaleźć w następujących tematach:
Android,
iOS
Wytyczne dotyczące identyfikatora zadania
Podczas tworzenia identyfikatorów zadań postępuj zgodnie z tymi wskazówkami dotyczącymi treści i formatu:
- Tworzenie unikalnych identyfikatorów zadań
- Nie ujawniaj żadnych informacji umożliwiających identyfikację osób ani danych w formie zwykłego tekstu.
- Użyj prawidłowych ciągów Unicode.
- Użyj maksymalnie 64 znaków.
- Nie wpisuj żadnego z tych znaków ASCII: „/”, „:”, „”, „?” ani „#”.
- Normalizuj dane zgodnie z formularzem normalizacji Unicode C.
Oto kilka przykładów prawidłowych identyfikatorów zadań:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFm wysokiej jakości2NzNkM2Jk
Poniższa tabela zawiera przykłady nieobsługiwanych identyfikatorów zadań:
| Nieobsługiwane identyfikatory zadań | Przyczyna |
|---|---|
| 8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | narusza wymagania dotyczące informacji umożliwiających identyfikację oraz znaków: przecinków, kropek, dwukropków i ukośników; |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Narusza wymagania dotyczące informacji umożliwiających identyfikację. |
| 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Narusza wymagania dotyczące informacji umożliwiających identyfikację oraz znaków: odstępów, przecinków i cudzysłowów. Nazwa przekracza 64 znaki. |
Więcej zasobów
Aby zobaczyć konkretne pola zawarte w każdej strukturze danych, zapoznaj się z dokumentacją API dla DeliveryVehicle (gRPC, REST) i Task (gRPC, REST).
Żywotność pojazdu
Obiekt DeliveryVehicle reprezentuje pojazd dostawczy na pierwszą lub ostatnią milę.
Tworzysz obiekt DeliveryVehicle za pomocą:
- Identyfikator projektu Google Cloud, który zawiera konto usługi używane do wywoływania interfejsów API Fleet Engine.
- Identyfikator pojazdu należącego do klienta.
Użyj unikalnego identyfikatora pojazdu. Nie używaj ponownie identyfikatora pojazdu, chyba że dla oryginalnego pojazdu nie ma aktywnych zadań.
Fleet Engine po 7 dniach automatycznie usuwa obiekty DeliveryVehicle, które nie zostały zaktualizowane za pomocą UpdateDeliveryVehicle. Aby sprawdzić, czy pojazd istnieje:
- Zadzwoń pod numer
UpdateDeliveryVehicle. - Jeśli pojawi się błąd NOT_FOUND, wywołaj
CreateDeliveryVehicle, aby odtworzyć pojazd. Jeśli połączenie zwraca pojazd, wciąż można go zaktualizować.
Atrybuty pojazdu
Encja DeliveryVehicle zawiera powtarzane pole DeliveryVehicleAttribute. Interfejs ListDeliveryVehicles API zawiera pole filter, które może ograniczyć zwracane jednostki DeliveryVehicle do tych o określonych atrybutach. DeliveryVehicleAttribute nie ma wpływu na zachowanie routingu Fleet Engine.
Nie podawaj w atrybutach informacji umożliwiających identyfikację osób ani informacji poufnych, ponieważ to pole może być widoczne dla użytkowników.
Życie zadania
W Fleet Engine możesz tworzyć i aktualizować zadania, a także wysyłać do nich zapytania, korzystając z interfejsów gRPC lub REST interfejsu Deliveries API.
Obiekt Task ma pole stanu, które pozwala śledzić postęp jego cyklu życia. Wartości zostaną zmienione z OPEN na CLOSED (zamknięte). Nowe zadania są tworzone w stanie OTWÓRZ, co oznacza, że:
- Zadanie nie zostało jeszcze przypisane do pojazdu dostawczego.
- Pojazd nie przejechał jeszcze przypisanego do zadania postoju.
Wskazówki dotyczące zadań
Zadanie możesz przypisać do pojazdu tylko wtedy, gdy jest on OTWARTY.
Zadanie możesz anulować, usuwając je z listy przystanków. Spowoduje to automatyczne ustawienie stanu zadania na ZAMKNIĘTE.
Gdy pojazd zadania zakończy zadanie:
Zmień pole wyniku zadania na SUCCEEDED lub FAILED.
Podaj sygnaturę czasową zdarzenia.
Biblioteka JavaScript Fleet Tracking wskazuje następnie wynik zadania, a stan zadania jest automatycznie ustawiany na ZAMKNIĘTE. Więcej informacji znajdziesz w artykule Śledzenie floty przy użyciu biblioteki JavaScript Fleet Tracking.
Tak jak w przypadku pojazdów, Fleet Engine usuwa zadania, które nie zostały zaktualizowane po 7 dniach, a jeśli próbujesz utworzyć zadanie o już istniejącym identyfikatorze, zwraca on błąd.
Uwaga: Fleet Engine nie obsługuje usuwania zadań. Usługa automatycznie usuwa zadania po 7 dniach bez aktualizacji. Jeśli chcesz przechowywać dane zadania dłużej niż 7 dni, musisz wdrożyć tę funkcję samodzielnie.
Atrybuty zadania
Encja Task zawiera powtarzające się pole TaskAttribute, które może zawierać wartość jednego z 3 typów: ciągu znaków, liczby i wartości logicznej. Interfejs ListTasks API zawiera pole filter, które może ograniczyć zwracane jednostki Task do tych o określonych atrybutach. Atrybuty zadań nie mają wpływu na zachowanie routingu Fleet Engine.
Nie podawaj w atrybutach informacji umożliwiających identyfikację osób ani innych informacji poufnych, ponieważ mogą one być widoczne dla użytkowników.
Zarządzanie cyklem życia pojazdu i zadań
Przypomnienie: Twój system wewnętrzny działa jako zaufane źródło danych, które interfejs Fleet Engine Deliveries API uzupełnia w Twoim imieniu.
Aby zarządzać cyklem życia pojazdów i zadań w systemie, użyj interfejsu Fleet Engine Deliveries API do tworzenia, aktualizowania i śledzenia pojazdów oraz powiązanych z nimi zadań.
Jednocześnie aplikacja sterownika komunikuje się bezpośrednio z Fleet Engine, aby aktualizować informacje o lokalizacji urządzenia i trasach. Pozwala on Fleet Engine skutecznie zarządzać lokalizacją w czasie rzeczywistym. Funkcja ta wysyła lokalizację bezpośrednio do biblioteki śledzenia, za pomocą której możesz następnie informować klientów o stanie zamówienia.
Załóżmy na przykład, że masz taki scenariusz:
- Kierowca zbliża się do przystanku dostawy. Aplikacja sterownika wysyła swoją lokalizację do Fleet Engine.
- Fleet Engine wysyła lokalizację urządzenia do biblioteki śledzenia, której aplikacja używa, aby poinformować klienta o tym, jak blisko znajduje się paczka.
- Gdy kierowca zakończy dostawę, klika przycisk „Dostawa przesyłki” w aplikacji kierowcy.
- Działanie „Dostawa dostarczona” powoduje wysłanie informacji do Twojego systemu backendu, który wykonuje niezbędne czynności w ramach weryfikacji firmy.
- Twój system potwierdza zadanie jako SUCCEEDED i aktualizuje Fleet Engine za pomocą interfejsu Deliveries API.
Poniższy diagram przedstawia te procesy na poziomie ogólnym. Pokazuje też standardowe relacje między Twoim systemem, klientem i Fleet Engine.
Zarządzanie tokenami klientów
Aktualizacje lokalizacji pochodzące z aplikacji sterownika i wysyłane bezpośrednio do Fleet Engine wymagają tokenów autoryzacji. Oto zalecane podejście do obsługi aktualizacji dostarczonych przez klienta do Fleet Engine:
Wygeneruj token za pomocą roli konta usługi Fleet Engine Delivery UnTrusted Driver User (Użytkownik niezaufanych sterowników Fleet Engine Delivery).
Podaj aplikację sterownika z tokenem o ograniczonym zakresie. Ten zakres umożliwia aktualizowanie lokalizacji urządzenia tylko we Fleet Engine.
To podejście daje pewność, że połączenia pochodzące z urządzeń mobilnych – uważanych za środowiska o niskim zaufaniu – są zgodne z zasadą jak najmniejszych uprawnień.
Inne role konta usługi
Jeśli zamiast tego chcesz zezwolić aplikacjom sterownika na dokonywanie bezpośrednich aktualizacji Fleet Engine poza tymi, które są ograniczone do roli niezaufanego kierowcy, na przykład do wykonywania niektórych aktualizacji zadań, możesz użyć roli Zaufany kierowca. Informacje o modelu, który korzysta z roli zaufanego kierowcy, znajdziesz w artykule o modelu zaufanego sterownika.
Więcej informacji o wykorzystywaniu ról niezaufanych i zaufanych sterowników znajdziesz w artykule Konfigurowanie projektu Cloud.
Wyznacz dzień pracy
Z tabeli poniżej dowiesz się, jak może wyglądać dzień pracy w firmach transportowych i logistycznych. Szczegóły Twojej firmy mogą się różnić, ale możesz sprawdzić, jak możesz wymodelować dzień pracy.
| Godzina | Ćwiczenie | Modelowanie |
|---|---|---|
| W ciągu 24 godzin od początku dnia | Dyspozytor przypisuje przesyłki do pojazdów lub tras dostawy. | W Fleet Engine możesz z wyprzedzeniem tworzyć zadania związane z dostawami, odbiorami, przerwami itp. Możesz na przykład utworzyć zadanie związane z odbiorem przesyłki, zadanie związane z dostawą przesyłki, zaplanowaną niedostępność lub zaplanowane zatrzymanie.
Po określeniu zestawu paczek i kolejności ich dostarczania przypisz do pojazdu zadania. |
| Początek dnia | Kierowca zaczyna dzień w salonie, logując się w aplikacji Driver. | Zainicjuj interfejs Delivery Driver API. W razie potrzeby utwórz pojazd dostawczy we Fleet Engine. |
| Kierowca wczytuje przesyłki do pojazdu dostawczego, skanując przesyłki. | Jeśli zadania związane z dostawą nie zostały utworzone z wyprzedzeniem, utwórz zadania związane z dostawą przesyłki podczas skanowania. | |
| Kierowca potwierdza kolejność zadań do wykonania. | Jeśli nie zostały utworzone wcześniej, utwórz zadania odbioru dostawy, zaplanowaną niedostępność i zaplanowane przystanki. | |
| Kierowca wyjeżdża z zajazdu i zobowiązuje się do wykonania kolejnej liczby zadań do wykonania. | Przypisz do pojazdu wszystkie zadania lub podzbiór zadań, zatwierdzając ich kolejność. | |
| Kierowca dostarcza przesyłkę. | Po dotarciu na miejsce postoju wykonaj czynności związane z przystankiem pojazdu. Po dostarczeniu przesyłki zamknij zadanie dostawy i opcjonalnie zapisz stan wysyłki i inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem jazdy na następnym przystanku wykonaj działania związane z zatrzymaniem pojazdu i pojazdem na następny przystanek. | |
| Kierowca spotyka się z pojazdem dostawczym, aby przekazać do niego kolejne przesyłki. | Miejsce, w którym odbywa się przesiadka między pojazdami podającymi a pojazdami dostawczymi, powinno być modelowane jako zaplanowane przystanek.
Po przeniesieniu i zeskanowaniu przesyłek utwórz zadania związane z dostawą, jeśli nie zostały jeszcze utworzone. Następnie zaktualizuj kolejność ukończenia zadań, przypisując zadania do pojazdu i aktualizując kolejność zadań. |
|
| Kierowca otrzymuje powiadomienie o prośbie o odbiór. | Po zaakceptowaniu prośby o odbiór utwórz zadanie odbioru przesyłki. Następnie zaktualizuj kolejność wykonywania zadań, przypisując zadania do pojazdu i aktualizując kolejność zadań. | |
| Południe | Kierowca robi sobie przerwę obiadową. | Jeśli lokalizacja jest powiązana z zadaniem niedostępności, traktuj ją jak każde inne zadanie. Wykonuj czynności związane z pojazdem, który zatrzymuje się na przystanku, zatrzymuje się i pojazd w drodze do następnego przystanku.
W przeciwnym razie nie musisz podejmować żadnych działań do końca przerwy. Aby usunąć zadanie, potwierdź kolejne i pozostałe zadania oraz zaktualizuj kolejność zadań. |
| Kierowca odbiera paczkę. | Model jest podobny do przystanku dostawy. Wykonuj działania związane z pojazdem na postoju i zamykaniem zadania oraz opcjonalnie zachowuj stan przesyłki i inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem jazdu na następny przystanek wykonaj działania związane z zatrzymaniem pojazdu i pojazdem na następny przystanek. Uwaga: aby zapewnić prawidłowe płatności, wszystkie odbiory muszą mieć odpowiadające im zadanie dostawy. Jeśli w tym dniu odbiór ma zostać dostarczony do innej lokalizacji na tej samej trasie kierowcy, zalecamy zamodelowanie tego zadania dostawy jako dowolnego innego zadania dostawy na trasie. Jeśli kierowca przynosi odbiór z powrotem do magazynu, zalecamy utworzenie zadania dostawy w jego miejscu. | |
| Kierowca zatrzymuje się, aby odebrać przesyłki ze skrzynki referencyjnej. | Odbiór jest modelowany tak samo jak każdy inny punkt odbioru. Wykonuj działania związane z pojazdem na postoju i zamykaniem zadania. Po wykonaniu wszystkich zadań na przystanku i rozpoczęciu jazdy do następnego przystanku wykonaj działania związane z zatrzymaniem pojazdu i pojazdem na następny przystanek. | |
| Kierowca otrzymuje powiadomienie o przekierowaniu przesyłki w inne miejsce. | Ustaw pierwotny stan zadania dostawy na UKOŃCZONE i utwórz nowe zadanie dostawy dla nowego miejsca dostawy. Więcej informacji znajdziesz w artykule Przekierowywanie wysyłki. | |
| Kierowca próbował dostarczyć paczkę, ale nie mógł tego zrobić. | Jest to modelowane podobnie do udanego zatrzymania dostarczania, przez co zadanie wyświetlania jest oznaczone jako ukończone. Wykonuj działania związane z pojazdem na przystanku. Jeśli nie dostarczysz przesyłki, zamknij zadanie i opcjonalnie zapisz stan wysyłki i inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem jazdu na następny przystanek wykonaj działania związane z zatrzymaniem pojazdu i pojazdem na następny przystanek. | |
| Kierowca otrzymał powiadomienie, że powinien wstrzymać (nie dostarczyć) przesyłkę. | Po otrzymaniu i potwierdzeniu powiadomienia ustaw stan zadania na UKOŃCZONE. | |
| Kierowca został poinformowany o konieczności dostarczenia określonej przesyłki w celu zmiany zamówienia w ramach zobowiązania. | Zaktualizuj kolejność zadań. | |
| Kierowca decyduje się dostarczyć przesyłkę bez zamówienia. | Zaktualizuj kolejność zadań, a następnie kontynuuj normalne działanie. | |
| Kierowca dostarcza kilka przesyłek do jednej lokalizacji. | Ten proces jest podobny do pojedynczego postoju dostawy. Po dotarciu na przystanek wykonaj czynności związane z przystankiem pojazdu. Po dostarczeniu każdej przesyłki zamknij każde zadanie i opcjonalnie zapisz stan wysyłki i inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem jazdu na następny przystanek wykonaj działania związane z zatrzymaniem pojazdu i pojazdem na następny przystanek. | |
| Koniec dnia | Kierowca wraca do składu. | Jeśli kierowca wróci do magazynu z przesyłki, musisz też utworzyć i zamknąć każdą paczkę jako zadanie dostawy, aby zapewnić prawidłowe rozliczenia. Możesz to zrobić, modelując magazyn tak jak w przypadku każdego innego miejsca dostawy. Jeśli oddział nie jest używany jako postój na dostawy, możesz opcjonalnie zamodelować go na zaplanowanym przystanku. Modelowanie przystanku pozwala kierowcom zobaczyć trasę z powrotem do zajezdni oraz szacowany czas dotarcia na miejsce. |
Jak działają aktualizacje lokalizacji
Aby uzyskać najlepszą wydajność Fleet Engine, zapewnij jej strumień aktualizacji lokalizacji pojazdów. Aby zapewnić aktualizacje, skorzystaj z jednego z tych sposobów:
- Użyj pakietu SDK sterownika – Android, iOS – najprostszy sposób.
- Użyj kodu niestandardowego, który jest przydatny, jeśli lokalizacje są przekazywane przez Twój backend lub używasz urządzeń innych niż Android lub iOS.
Niezależnie od tego, jak aktualizujesz lokalizację pojazdu, Twój backend odpowiada za aktualizowanie Fleet Engine, gdy pojazd dostawczy w drodze do zatrzymania (w tym do stacji) lub gdy dotrze na postój. Fleet Engine nie wykrywa tych zdarzeń automatycznie.
Miejsca postoju i dostawy pojazdów
Zatrzymanie pojazdu to miejsce, w którym pojazd kurierski wykonuje zadanie dostawy lub inne zadanie. Może to być punkt dostępu, taki jak stacja dokująca do załadunku, lub lokalizacja oddzielona od drogi.
Lokalizacja dostawy to miejsce, w którym zostanie dostarczona lub odebrana. Dojazd do miejsca dostawy i z niego może wymagać przejścia z przystanku pieszo.
Jeśli np. kierowca dostarcza przesyłkę do sklepu w centrum handlowym, samochód dostawczy zatrzymuje się na parkingu centrum handlowym w pobliżu najbliższego wejścia. To jest przystanek dla pojazdów. Następnie kierowca idzie z postoju do lokalizacji w centrum handlowym, w którym znajduje się sklep. Jest to miejsce dostawy.
Aby zapewnić użytkownikom jak największą wygodę śledzenia przesyłek, zastanów się, w jaki sposób zadania związane z dostawą są przypisane do postojów pojazdów. Pamiętaj, że liczba postojów pozostałych pojazdów związanych z zadaniami związanymi z dostawą jest zgłaszana użytkownikowi, aby mógł śledzić postęp przesyłki.
Jeśli na przykład kierowca dostarcza wiele dostaw do jednego budynku biurowego, możesz przypisać wszystkie zadania związane z dostawą do jednego postoju. Jeśli każde zadanie związane z dostawą jest przypisane do własnego postoju pojazdu, śledzenie przesyłki będzie mniej przydatne dla użytkowników, ponieważ śledzenie przesyłki jest dostępne tylko wtedy, gdy pojazd znajduje się w ograniczonej liczbie postojów przed miejscem docelowym. Realizacja wielu zatrzymań pojazdów w krótkim czasie nie daje użytkownikowi dużo czasu na śledzenie postępów dostawy.
Używanie mobilnych pakietów SDK
Przed wykonaniem jakichkolwiek wywołań do pakietu Driver SDK musisz go zainicjować.
Inicjowanie interfejsu Delivery Driver API
Zanim zainicjujesz interfejs Delivery Driver API w pakiecie Driver SDK, zainicjuj pakiet Navigation SDK. Następnie zainicjuj interfejs Delivery Driver API w następujący sposób:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Przypadki użycia
W tej sekcji opisujemy, jak wykorzystać interfejs Deliveries API do modelowania typowych przypadków użycia.
Unikalne identyfikatory encji
Format i wartość unikalnych identyfikatorów jednostek używanych w wywołaniach REST są nieprzejrzyste dla Fleet Engine. Unikaj stosowania identyfikatorów automatycznie zwiększających wartość i upewnij się, że nie zawiera on żadnych informacji umożliwiających identyfikację osoby (takich jak numer telefonu kierowcy).
Utwórz pojazd
Pojazd możesz utworzyć za pomocą pakietu Driver SDK albo środowiska serwera za pomocą gRPC lub REST.
gRPC
Aby utworzyć nowy pojazd, wykonaj wywołanie CreateDeliveryVehicle do Fleet Engine.
Atrybuty nowego pojazdu dostawczego możesz określić za pomocą obiektu CreateDeliveryVehicleRequest. Pamiętaj, że wartości określone w polu Name są ignorowane zgodnie ze wskazówkami interfejsu API w przypadku identyfikatorów określonych przez użytkowników.
Identyfikator pojazdu należy skonfigurować w polu DeliveryVehicleId.
Podczas tworzenia obiektu DeliveryVehicle możesz opcjonalnie określić te pola:
- Atrybuty
- LastLocation
- Typ
Nie ustawiaj innych pól. Jeśli to zrobisz, Fleet Engine zwróci błąd, ponieważ te pola są tylko do odczytu lub można je zaktualizować tylko przez wywołanie UpdateDeliveryVehicle.
Aby utworzyć pojazd bez ustawiania żadnych pól opcjonalnych, możesz pozostawić
nieustawione pole DeliveryVehicle w CreateDeliveryVehicleRequest.
Z przykładu poniżej dowiesz się, jak utworzyć pojazd przy użyciu biblioteki Java gRPC:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć pojazd ze środowiska serwera, wykonaj wywołanie HTTP REST do CreateDeliveryVehicle:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> to unikalny identyfikator pojazdu dostawczego w Twojej flocie.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść POST reprezentuje encję DeliveryVehicle do utworzenia. Możesz określić te opcjonalne pola:
- atrybuty
- lastLocation
- typ
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
Fleet Engine ignoruje pole name encji DeliveryVehicle zgodnie ze wskazówkami interfejsu API dotyczącymi identyfikatorów określonych przez użytkowników.
Nie ustawiaj innych pól. Jeśli to zrobisz, Fleet Engine zwróci błąd, ponieważ te pola są tylko do odczytu lub można je zaktualizować tylko przez wywołanie UpdateDeliveryVehicle.
Aby utworzyć pojazd bez ustawiania żadnych pól, pozostaw treść żądania POST pustą. Nowo utworzony pojazd wyodrębnia następnie identyfikator pojazdu z parametru deliveryVehicleId w adresie URL żądania POST.
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Utwórz zadanie odbioru przesyłki
Zadanie odbioru przesyłki możesz utworzyć w pakiecie SDK Driver albo w środowisku serwera za pomocą gRPC lub REST.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC utworzyć zadanie odbioru przesyłki:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć zadanie odbioru przesyłki w środowisku serwera, wyślij wywołanie HTTP REST do CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> to unikalny identyfikator zadania. Nie może to być numer śledzenia przesyłki. Jeśli nie masz identyfikatorów zadań w systemie, możesz wygenerować unikalny identyfikator uniwersalny (UUID).
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość typ Type.PICKUP state State.OPEN trackingId Numer lub identyfikator, którego używasz do śledzenia przesyłki. plannedLocation Lokalizacja, w której zadanie ma zostać wykonane, w tym przypadku miejsce odbioru przesyłki. taskDuration Oczekiwany czas (w sekundach) potrzebny do odebrania przesyłki z miejsca odbioru. Pola opcjonalne:
Pole Wartość targetTimeWindow Przedział czasu, w którym należy wykonać zadanie. Nie ma to wpływu na zachowanie routingu. atrybuty Lista niestandardowych atrybutów zadania. Każdy atrybut musi mieć unikalny klucz.
Wszystkie pozostałe pola elementu są ignorowane podczas tworzenia. Fleet Engine zgłasza wyjątek, jeśli żądanie zawiera przypisanego deliveryVehicleId. Przypisujesz zadania za pomocą polecenia UpdateDeliveryVehicleRequest. Więcej informacji znajdziesz w artykułach Przypisywanie zadań do pojazdu i UpdateDeliveryVehicleRequest.
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Tworzenie zadania dostawy przesyłki
Utwórz zadanie dostarczenia przesyłki za pomocą pakietu SDK sterownika albo w środowisku serwera za pomocą gRPC lub REST.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC utworzyć zadanie dostawy przesyłki:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć zadanie dostawy przesyłki w środowisku serwera za pomocą gRPC lub REST, wykonaj wywołanie HTTP REST CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> to unikalny identyfikator zadania. Nie może to być numer śledzenia przesyłki. Jeśli nie masz identyfikatorów zadań w systemie, możesz wygenerować unikalny identyfikator uniwersalny (UUID).
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość typ Type.DELIVERY state State.OPEN trackingId Numer lub identyfikator, którego używasz do śledzenia przesyłki. plannedLocation Lokalizacja, w której zadanie ma zostać wykonane, w tym przypadku miejsce dostawy tej przesyłki. taskDuration Oczekiwany czas dostarczenia przesyłki do miejsca dostawy (w sekundach). Pola opcjonalne:
Pole Wartość targetTimeWindow Przedział czasu, w którym należy wykonać zadanie. Nie ma to wpływu na zachowanie routingu. atrybuty Lista niestandardowych atrybutów zadania. Każdy atrybut musi mieć unikalny klucz.
Wszystkie pozostałe pola elementu są ignorowane podczas tworzenia. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator purchaseVehicleId. Przypisujesz zadania za pomocą polecenia UpdateDeliveryVehicleRequest. Więcej informacji znajdziesz w artykułach Przypisywanie zadań do pojazdu i UpdateDeliveryVehicleRequest.
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Zbiorcze tworzenie zadań
Możesz utworzyć grupę zadań ze środowiska serwera za pomocą gRPC lub REST.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC utworzyć 2 zadania – dotyczące dostawy i odbioru w tej samej lokalizacji:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Delivery Task settings
Task deliveryTask = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("delivery-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8312508") // Task ID assigned by the Provider
.setTask(deliveryTask) // Initial state
.build();
// Pickup Task settings
Task pickupTask = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("pickup-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header or parent fields
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(pickupTask) // Initial state
.build();
// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;
// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
BatchCreateTasksRequest.newBuilder()
.setParent(parent)
.addRequests(createDeliveryTaskRequest)
.addRequests(createPickupTaskRequest)
.build();
// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.
try {
BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć zadanie dostawy i odbioru w środowisku serwera, wyślij wywołanie HTTP REST do BatchCreateTasks:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję BatchCreateTasksRequest:
Pola wymagane:
Pole Wartość żądania Tablica< CreateTasksRequest>Pola opcjonalne:
Pole Wartość nagłówek `DeliveryRequestHeader`
Każdy element CreateTasksRequest w elemencie requests musi przechodzić te same reguły weryfikacji co żądanie CreateTask z wyjątkiem pól parent i header, które są opcjonalne. Jeśli je ustawisz, muszą być identyczne z odpowiednimi polami na najwyższym poziomie BatchCreateTasksRequest. Zobacz na temat tworzenia zadania odbioru przesyłki i tworzenia takiego zadania, aby poznać reguły weryfikacji dla każdego z nich.
Więcej informacji znajdziesz w dokumentacji API dotyczącej BatchCreateTasks (gRPC, REST).
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Zaplanowana niedostępność
Zadanie wskazujące niedostępność (np. dotyczące kierowców lub tankowania pojazdów) możesz utworzyć za pomocą pakietu SDK Driver albo w środowisku serwera za pomocą gRPC lub REST. Zaplanowane zadanie niedostępności nie może zawierać identyfikatora śledzenia. Opcjonalnie możesz podać lokalizację.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC utworzyć zadanie niedostępności:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć zadanie niedostępności w środowisku serwera, wykonaj wywołanie HTTP REST do CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> to unikalny identyfikator zadania. Jeśli nie masz identyfikatorów zadań w systemie, możesz wygenerować unikalny identyfikator uniwersalny (UUID).
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość typ Type.UNAVAILABLE state State.OPEN taskDuration Czas trwania przerwy w sekundach. Pola opcjonalne:
Pole Wartość plannedLocation Miejsce, w którym przerwa ma nastąpić w konkretnym miejscu.
Wszystkie pozostałe pola elementu są ignorowane podczas tworzenia. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator purchaseVehicleId. Przypisujesz zadania za pomocą polecenia UpdateDeliveryVehicleRequest. Więcej informacji znajdziesz w artykułach Przypisywanie zadań do pojazdu i UpdateDeliveryVehicleRequest.
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
Zaplanowane przystanki
Zaplanowane zadanie zatrzymania możesz utworzyć za pomocą pakietu SDK sterowników albo środowiska serwera za pomocą gRPC lub REST. Zaplanowane zadanie zatrzymania nie może zawierać identyfikatora śledzenia.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC utworzyć zadanie zaplanowanego zatrzymania:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby utworzyć zaplanowane zadanie zatrzymania w środowisku serwera, wykonaj wywołanie HTTP REST do CreateTask:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> to unikalny identyfikator zadania. Jeśli nie masz identyfikatorów zadań w systemie, możesz wygenerować unikalny identyfikator uniwersalny (UUID).
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość typ Type.SCHEDULED_STOP state State.OPEN plannedLocation Lokalizacja przystanku. taskDuration Oczekiwany czas postoju w sekundach. Pola opcjonalne:
- Brak
Wszystkie pozostałe pola elementu są ignorowane podczas tworzenia. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator purchaseVehicleId. Przypisujesz zadania za pomocą polecenia UpdateDeliveryVehicleRequest. Więcej informacji znajdziesz w artykułach Przypisywanie zadań do pojazdu i UpdateDeliveryVehicleRequest.
Przykładowe polecenie curl:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
Ustaw docelowy przedział czasu
Docelowy przedział czasu to TimeWindow, w którym zadanie powinno zostać wykonane. Jeśli na przykład przekazujesz odbiorcom informacje o czasie dostawy, możesz użyć tego pola w celu uchwycenia tego przedziału i wygenerowania alertów lub analizy wyników po podróży.
Docelowy przedział czasu składa się z godziny rozpoczęcia i zakończenia i można go ustawić dla dowolnego typu zadania. Docelowy przedział czasu nie ma wpływu na zachowanie routingu.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC ustawić okno czasu zadania:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby ustawić przedział czasu zadania przez HTTP, wywołaj UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> to unikalny identyfikator zadania.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość targetTimeWindow Przedział czasu, w którym należy wykonać zadanie. To ustawienie nie ma wpływu na zachowanie routingu Pola opcjonalne:
- Brak
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Ustaw konfigurację widoczności śledzenia zadań
Widoczność danych w bibliotece śledzenia przesyłek oraz danych zwróconych z połączenia do usługi GetTaskTrackingInfo można kontrolować dla poszczególnych zadań, ustawiając dla nich właściwość TaskTrackingViewConfig. Więcej informacji znajdziesz w artykule Aktywne zadania związane z pojazdem. Możesz to zrobić podczas tworzenia lub aktualizowania zadania. Poniżej znajdziesz przykład aktualizowania zadania przy użyciu tej konfiguracji:
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC ustawić konfigurację widoku śledzenia zadań:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby skonfigurować okno konfiguracji widoku śledzenia zadań przy użyciu protokołu HTTP, wywołaj UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> to unikalny identyfikator zadania.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość taskTrackingViewConfig Konfiguracja śledzenia zadań określająca, które elementy danych są widoczne dla użytkowników w jakich okolicznościach. Pola opcjonalne:
- Brak
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
Przypisywanie zadań do pojazdu
Aby przypisać zadania do pojazdu dostawczego, zaktualizuj jego kolejność zadań. Kolejność zadań dla pojazdu jest określana na podstawie listy postojów w pojeździe firmowym. Do każdego z przystanków możesz przypisać 1 lub więcej zadań. Więcej informacji znajdziesz w sekcji Aktualizowanie kolejności zadań.
Aby zmienić przesyłkę z jednego pojazdu na inny, zamknij pierwotne zadanie, a następnie odtwórz je ponownie, zanim przypiszesz nowy pojazd. Jeśli zaktualizujesz kolejność zadań dla zadania, które jest już przypisane do innego pojazdu, pojawi się błąd.
Zaktualizuj kolejność zadań
Zadania dotyczące zamówień przypisanych do pojazdu możesz wykonywać za pomocą pakietu SDK Driver albo środowiska serwera. Nie używaj obu metod, aby uniknąć warunków wyścigu i utrzymać jedno źródło wiarygodnych danych.
Gdy zaktualizujesz kolejność zadań w pojeździe, nowe zasady wykonają też te czynności:
- Przypisuje zadania, które nie pojawiły się w pojeździe.
- Zamyka wszystkie zadania, które zostały wcześniej przypisane do pojazdu, ale nie znajdują się w zaktualizowanej kolejności.
Aby zmienić przesyłkę z jednego pojazdu na inny, zamknij pierwotne zadanie, a następnie odtwórz je ponownie, zanim przypiszesz do nowego pojazdu. Jeśli zaktualizujesz kolejność zadań dla zadania, które jest już przypisane do innego pojazdu, pojawi się błąd.
Kolejność zadań możesz zmienić w każdej chwili.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC zaktualizować kolejność zadań w pojeździe:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby zaktualizować kolejność zadań dla pojazdu ze środowiska serwera, wyślij wywołanie HTTP REST do UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> to unikalny identyfikator pojazdu dostawczego w Twojej flocie, dla którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany podczas tworzenia pojazdu.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję DeliveryVehicle:
Pola wymagane:
Pole Wartość remainingVehicleJourneySegments Lista segmentów przebiegu dla zadań w kolejności, w której mają być wykonane. Pierwsze zadanie na liście jest wykonywane jako pierwsze. pozostałe segmentyPojazdu[i].stop Przystanek zadania i na liście. pozostałePojazdyJourneySegments[i].stop.plannedLocation Planowana lokalizacja przystanku. pozostałePojazdyJourneySegments[i].stop.zadania Lista zadań do wykonania na tym przystanku. remainingVehicleJourneySegments[i].stop.state State.NEW Pola opcjonalne:
- Brak
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Pojazd jedzie do następnego przystanku
Usługa Fleet Engine musi być powiadamiana, gdy pojazd wychodzi ze postoju lub rozpoczyna nawigację. Możesz to zrobić za pomocą pakietu SDK sterownika albo ze środowiska serwera przy użyciu gRPC lub REST. Nie używaj obu tych metod, by uniknąć warunków wyścigu i zachować jedno źródło wiarygodnych informacji.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC, aby powiadomić Fleet Engine o tym, jak pojazd jest w drodze do następnego postoju.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby powiadomić Fleet Engine, że pojazd jest w drodze do następnego przystanku ze środowiska serwera, wywołaj HTTP REST UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> to unikalny identyfikator pojazdu dostawczego we flocie, w przypadku którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany podczas tworzenia pojazdu.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję DeliveryVehicle:
Pole wymagane:
Pole Wartość remainingVehicleJourneySegments Lista pozostałych przystanków z ich stanami oznaczonymi jako State.NEW. Pierwszy przystanek na liście musi mieć stan oznaczony jako State.ENROUTE. Pola opcjonalne:
- Brak
Pozostałe pola elementu są ignorowane w przypadku powiadomienia.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Zaktualizuj lokalizację pojazdu
Jeśli nie używasz pakietu SDK kierowcy do aktualizacji lokalizacji pojazdu, możesz nawiązać bezpośrednie połączenie do Fleet Engine z informacjami o lokalizacji pojazdu. W przypadku każdego aktywnego pojazdu Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę i nie częściej niż co 5 sekund.
gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC zaktualizować lokalizację pojazdu w Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby zaktualizować lokalizację pojazdu we Fleet Engine za pomocą protokołu HTTP REST, wywołaj UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> to unikalny identyfikator pojazdu dostawczego z Twojej floty lub tego, którego lokalizację chcesz zaktualizować. Jest to identyfikator podany podczas tworzenia pojazdu.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję DeliveryVehicle:
Pole wymagane:
Pole Wartość lastLocation.supplementalLocation Lokalizacja pojazdu. lastLocation.supplementalLocationTime Ostatnia znana sygnatura czasowa, z którą pojazd znajdował się w tej lokalizacji. lastLocation.supplementalLocationSensor Powinno być w nim miejsce CUSTOMER_SUPPLIED_LOCATION. Pola opcjonalne:
Pole Wartość lastLocation.supplementalLocationAccuracy Dokładność podanej lokalizacji w metrach.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
Pojazd wjeżdżający na przystanek
Usługa Fleet Engine musi być powiadamiana, gdy pojazd się zatrzyma. Możesz to zrobić za pomocą pakietu SDK sterownika albo środowiska serwera przy użyciu gRPC lub REST. Nie używaj obu tych metod, by uniknąć warunków wyścigu i zachować jedno źródło wiarygodnych informacji.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC, aby powiadomić Fleet Engine o zatrzymaniu pojazdu:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby powiadomić Fleet Engine o przybyciu pojazdu na postój ze środowiska serwera, wykonaj wywołanie HTTP REST do UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> to unikalny identyfikator pojazdu dostawczego we flocie, w przypadku którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany podczas tworzenia pojazdu.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję DeliveryVehicle:
Pola wymagane:
Pole Wartość remainingVehicleJourneySegments Przystanek, na którym się znajdujesz, ma stan ustawiony jako State.ARRIVED, a następnie lista pozostałych przystanków z ich stanami oznaczonymi jako State.NEW. Pola opcjonalne:
- Brak
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Pojazd zatrzymuje się
Usługa Fleet Engine musi być powiadamiana o zatrzymaniu pojazdu. Spowoduje to ustawienie wszystkich zadań powiązanych z przystankiem w stanie ZAMKNIĘTE. Powiadomień Fleet Engine możesz wysłać za pomocą pakietu SDK sterownika albo ze środowiska serwera przy użyciu gRPC lub REST. Nie używaj obu tych metod, aby uniknąć wyścigów i zachować jedno źródło wiarygodnych informacji.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC, aby powiadomić Fleet Engine o zatrzymaniu pojazdu.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby powiadomić Fleet Engine o zakończeniu zatrzymania w środowisku serwera, wykonaj wywołanie HTTP REST do UpdateDeliveryVehicle:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> to unikalny identyfikator pojazdu dostawczego we flocie, w przypadku którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany podczas tworzenia pojazdu.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję DeliveryVehicle:
Pola wymagane:
Pole Wartość remaining_vehicle_journey_segments Zakończony postój nie powinien już znajdować się na liście pozostałych przystanków. Pola opcjonalne:
- Brak
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Aktualizowanie zadania
Większość pól zadań nie można zmienić. Możesz jednak modyfikować stan, wynik zadania, czas wyniku zadania, lokalizację wyniku zadania i atrybuty, bezpośrednio aktualizując element zadania. Jeśli na przykład zadanie nie zostało przypisane do pojazdu, możesz je zamknąć, bezpośrednio aktualizując jego stan.
gRPC
Oto przykład aktualizowania zadania za pomocą gRPC.
REST
Oto przykład aktualizowania zadania za pomocą REST.
Zamykanie zadania
Aby zamknąć zadanie przypisane do pojazdu, powiadom Fleet Engine o tym, że pojazd zakończył postoje, na którym to zadanie jest wykonywane, lub usuń je z listy postojów. Aby to zrobić, możesz ustawić listę pozostałych pojazdów zatrzymujący się tak samo jak podczas aktualizowania kolejności zadań dla pojazdu.
Jeśli zadanie nie zostało jeszcze przypisane do pojazdu i musi zostać zamknięte, zmień jego stan na ZAMKNIĘTE. Nie można jednak ponownie otworzyć zadania ZAMKNIĘTE.
Zakończenie zadania nie oznacza powodzenia ani niepowodzenia. Wskazuje on, że zadanie nie jest już uznawane za uruchomione. W przypadku śledzenia floty ważne jest, aby wskazać rzeczywisty wynik zadania, aby można było zobaczyć efekty realizacji.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby oznaczyć zadanie jako zamknięte w środowisku serwera, wyślij wywołanie HTTP REST do UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> to unikalny identyfikator zadania.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
W treści żądania musisz umieścić element Task:
Pola wymagane:
Pole Wartość state State.CLOSED Pola opcjonalne:
Pole Wartość taskOutcome Wynik.SUCCEEDED lub Wynik.FAILED taskOutcomeTime Czas ukończenia zadania. taskOutcomeLocation Lokalizacja, w której zostało wykonane zadanie. Domyślnie Fleet Engine ustawia ostatnią lokalizację pojazdu, chyba że ręcznie zastąpisz to ustawienie przez dostawcę.
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"state": "CLOSED",
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)"
}
EOM
Ustawianie lokalizacji wyniku zadania i wyniku
Zamknięcie zadania nie oznacza powodzenia ani niepowodzenia, wskazuje, że zadanie nie jest już w toku. W przypadku śledzenia floty ważne jest, aby wskazać rzeczywisty wynik zadania, aby można było przedstawić wynik dostawy i umożliwić naliczanie odpowiednich płatności za usługi. Po ustawieniu nie można zmienić wyniku zadania. Po ustawieniu czasu i lokalizacji wyników zadania można jednak zmienić.
Zadania ze stanem ZAMKNIĘTE mogą mieć wynik SUCCEEDED lub FAILED. Fleet Engine nalicza opłaty tylko za zadania związane z dostarczaniem o stanie SUCCEEDED.
Podczas zaznaczania wyniku zadania Fleet Engine automatycznie uzupełni lokalizację wyniku zadania ostatnią znaną lokalizacją pojazdu. Możesz zastąpić to zachowanie.
gRPC
Podczas określania wyniku zadania możesz ustawić lokalizację wyniku. Ustawienie lokalizacji uniemożliwia Fleet Engine ustawienie jej domyślnej wartości dla ostatniej lokalizacji pojazdu. Możesz też zastąpić lokalizację wyniku zadania ustawioną przez Fleet Engine później. Fleet Engine nigdy nie zastępuje podanej przez Ciebie lokalizacji wyniku zadania. Nie możesz ustawić lokalizacji wyniku zadania dla zadania, które nie ma ustawionego wyniku zadania. W jednym żądaniu możesz ustawić zarówno wynik, jak i wynik zadania.
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC ustawić wynik zadania na SUCCEEDED i ustawić lokalizację, w której zostało ono wykonane:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby oznaczyć zadanie jako ukończone w środowisku serwera, wyślij wywołanie HTTP REST do UpdateTask:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id> to unikalny identyfikator zadania.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi zawierać encję Task:
Pola wymagane:
Pole Wartość taskOutcome Wynik.SUCCEEDED lub Wynik.FAILED taskOutcomeTime Sygnatura czasowa ustawienia wyniku zadania (od dostawcy). Jest to data ukończenia zadania. Pola opcjonalne:
Pole Wartość taskOutcomeLocation Lokalizacja, w której zostało wykonane zadanie. Domyślnie Fleet Engine ustawia ostatnią lokalizację pojazdu, chyba że ręcznie zastąpisz to ustawienie przez dostawcę.
Pozostałe pola elementu zostaną zignorowane podczas aktualizacji.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Przekierowanie przesyłki
Po utworzeniu zadania dostawy nie można zmienić jego zaplanowanej lokalizacji. Aby przekierować przesyłkę, zamknij zadanie dostawy bez określania wyniku, a następnie utwórz nowe zadanie ze zaktualizowaną planowaną lokalizacją. Po utworzeniu nowego zadania przypisz je do tego samego pojazdu. Aby uzyskać więcej informacji, przeczytaj artykuł o zamykaniu zadania dostawy i przypisywaniu zadania.
Używanie modułów dostarczania i pojazdów dostawczych
Jeśli używasz pojazdów dostawczych do transportu przesyłek do pojazdów dostawczych w ciągu dnia, modeluj przeniesienie przesyłek jako zaplanowane zadanie postoju w pojazdach dostawczych. Aby zapewnić dokładne śledzenie lokalizacji, przypisuj zadanie dostawy tylko w przypadku przeniesionej przesyłki dopiero po załadowaniu jej do pojazdu dostawczego. Więcej informacji znajdziesz w artykule o zaplanowanym przystanku.
Przechowuj stan wysyłki i inne metadane
Po zakończeniu zadania dostawy rejestrowany jest w nim stan i wynik zadania. Możesz jednak zaktualizować inne metadane, które dotyczą dostawy. Aby przechowywać inne metainformacje, do których możesz się odwoływać poza usługą Fleet Engine, użyj identyfikatora śledzenia powiązanego z zadaniem jako klucza w tabeli zewnętrznej.
Więcej informacji znajdziesz w artykule Cykl życia zadania.
Wyszukiwanie pojazdu
Pojazd możesz wyszukać za pomocą pakietu SDK sterownika albo środowiska serwera za pomocą gRPC lub REST.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC do wyszukania pojazdu:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby wyszukać pojazd w środowisku serwera, wykonaj wywołanie HTTP REST do GetVehicle:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> to unikalny identyfikator zadania.
<vehicleId> to identyfikator pojazdu, którego szukasz.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi być pusta.
Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała element pojazdu.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Wyszukiwanie zadania
Zadanie możesz wyszukać w środowisku serwera za pomocą gRPC lub REST. Driver SDK nie obsługuje wyszukiwania zadań.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC do wyszukania zadania:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby wyszukać zadanie w środowisku serwera, wykonaj wywołanie HTTP REST do GetTask:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id> to unikalny identyfikator zadania.
<taskId> to identyfikator zadania do wyszukania.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Treść żądania musi być pusta.
Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała encję zadania.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
wyszukiwać informacje o zadaniach dostawy według identyfikatora śledzenia,
Informacje o zadaniach floty możesz wyszukiwać na różne sposoby, z których każdy ma inny cel:
- według identyfikatora zadania: używane przez użytkowników takich jak operatorzy floty, którzy mają dostęp do pełnego widoku danych zadania.
- za pomocą identyfikatora śledzenia: używane przez oprogramowanie klienta do przekazywania użytkownikowi ograniczonych informacji, np. o tym, kiedy paczka powinna dotrzeć do klienta.
Z tej sekcji dowiesz się, jak wyszukiwać informacje o zadaniach przy użyciu identyfikatora śledzenia. Jeśli chcesz wyszukać zadanie według identyfikatora zadania, zobacz Wyszukiwanie zadania.
Aby wyszukać informacje według identyfikatora śledzenia, możesz skorzystać z jednej z następujących metod:
Wymagania dotyczące wyszukiwania
Informacje o dostawie podane przez identyfikator śledzenia są zgodne z regułami widoczności określonymi w artykule Kontrolowanie widoczności monitorowanych lokalizacji.
Użyj Fleet Engine, aby wyszukać informacje o dostawie według identyfikatora śledzenia. Pakiet SDK sterownika nie obsługuje wyszukiwania informacji za pomocą identyfikatora śledzenia. Aby to zrobić w Fleet Engine, musisz użyć środowiska serwera lub przeglądarki.
Aby ograniczyć zagrożenia dla bezpieczeństwa, użyj możliwie najwęższego tokena. Jeśli na przykład używasz tokena konsumenta dostawy, wszystkie wywołania interfejsu Fleet Engine Deliveries API zwracają tylko informacje istotne dla tego użytkownika, takie jak firma kurierska lub odbiorca przesyłki. Wszystkie inne informacje w odpowiedziach zostaną usunięte. Więcej informacji o tokenach znajdziesz w sekcji Tworzenie tokena internetowego JSON (JWT) do autoryzacji.
Wyszukiwanie w Javie przy użyciu gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki Java gRPC wyszukiwać informacje o zadaniu dostawy według jego identyfikatora śledzenia.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Wyszukiwanie przy użyciu protokołu HTTP
Aby wyszukać zadanie dostawy w przeglądarce, wykonaj wywołanie HTTP REST do GetTaskTrackingInfo:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> to identyfikator śledzenia powiązany z zadaniem.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała encję taskTrackingInfo.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Wyświetlenie listy zadań
Możesz wyświetlać zadania ze środowiska serwera lub przeglądarki. Pakiet Driver SDK nie obsługuje wyświetlania listy zadań.
Wyświetlanie listy zadań wymaga szerokiego dostępu do zadań. Zadania związane z wyświetlaniem listy są przeznaczone tylko dla zaufanych użytkowników. Podczas tworzenia żądań zadań list należy używać tokenów uwierzytelniania floty usług dostarczania lub tokenów uwierzytelniania superużytkownika.
Na liście zadań zostaną usunięte te pola:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Zadania na liście można filtrować według większości właściwości zadań. Składnię zapytań filtrów znajdziesz na stronie AIP-160. Na liście poniżej znajdziesz prawidłowe właściwości zadań, których możesz używać do filtrowania:
- atrybuty
- delivery_vehicle_id
- state
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- typ
Użyj tych formatów pól wybranych na podstawie propozycji poprawy interfejsu API Google:
| Typ pola | Format | Przykład |
|---|---|---|
| Sygnatura czasowa | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
| Czas trwania | Liczba sekund, po których następuje s |
task_duration = 120s |
| Enum | Ciąg znaków | state = CLOSED AND type = PICKUP |
| Lokalizacja | point.latitude i point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Pełną listę operatorów zapytań filtrów znajdziesz w sekcji AIP-160.
Jeśli nie określisz zapytania filtra, zobaczysz wszystkie zadania.
Listy zadań są podzielone na strony. Rozmiar strony można określić w żądaniach zadań listy. Jeśli został określony rozmiar strony, liczba zwróconych zadań nie może być większa niż podany rozmiar strony. W przypadku braku rozmiaru strony używana jest rozsądna wartość domyślna. Jeśli żądany rozmiar strony przekracza wewnętrzną wartość maksymalną, używane jest wewnętrzne maksimum.
Lista zadań może zawierać token służący do odczytu następnej strony wyników. Aby pobrać następną stronę zadań, użyj tokena strony z żądaniem, które jest poza tym identyczne z poprzednim żądaniem. Gdy zwrócony token strony będzie pusty, nie będzie można pobrać więcej zadań.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC, aby wyświetlić listę zadań związanych z identyfikatorem shippingVehicleId i atrybutem zadania. Pomyślna odpowiedź może być nadal pusta. Pusta odpowiedź oznacza, że do zadań nie są powiązane żadne zadania z dostarczonym identyfikatorem pojazdu.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby wyświetlić listę zadań w przeglądarce, wykonaj wywołanie HTTP REST do ListTasks:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Aby zastosować filtr do wymienionych zadań, dołącz parametr „filtr” adresu URL z zapytaniem filtra ze zmianą znaczenia w adresie URL.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała dane o następującej strukturze:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Pomyślna odpowiedź może być nadal pusta. Pusta odpowiedź oznacza, że nie znaleziono żadnych zadań spełniających określone kryteria filtra.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Wyświetlenie listy pojazdów dostawczych
Możesz wyświetlać listę pojazdów realizujących dostawę ze środowiska serwera lub przeglądarki. Pakiet SDK Kierowcy nie obsługuje wyświetlania informacji o pojazdach dostarczających informacje.
Wyświetlanie informacji o pojazdach dostawczych wymaga szerokiego dostępu do pojazdów dostawczych i jest przeznaczone tylko dla zaufanych użytkowników. Używaj tokenów uwierzytelniania floty usług lub tokenów uwierzytelniania superużytkownika podczas tworzenia żądań pojazdów dostarczających listy.
Te pola zostały usunięte ze względu na ich wpływ na rozmiar odpowiedzi:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Pojazdy dostawcze z listy możesz filtrować według ich właściwości attributes. Aby na przykład wysłać zapytanie do atrybutu o kluczu my_key i wartości my_value, użyj funkcji attributes.my_key = my_value. Aby wysłać zapytanie o więcej atrybutów, złącz zapytania za pomocą logicznych operatorów AND i OR, jak w przykładzie attributes.key1 = value1 AND
attributes.key2 = value2. Pełny opis składni zapytań filtra znajdziesz w AIP-160.
Wymienione pojazdy dostawcze możesz filtrować według lokalizacji za pomocą parametru żądania viewport. Parametr żądania viewport definiuje widoczne obszary za pomocą 2 współrzędnych ograniczających: pary szerokości i długości geograficznej high (północny wschód) i low (południowy zachód). Żądania są odrzucane, jeśli zawierają dużą szerokość geograficzną, która jest geograficznie mniejsza niż niska.
Listy pojazdów realizujących wyświetlenia są domyślnie podzielone na strony, mając uzasadniony rozmiar. Jeśli podasz rozmiar strony, żądanie zwróci tylko nie więcej niż liczbę pojazdów określoną w limicie. Jeśli żądany rozmiar strony przekracza wewnętrzną wartość maksymalną, używane jest wewnętrzne maksimum. Domyślny i maksymalny rozmiar strony to 100 pojazdów.
Lista pojazdów realizujących dostawy może zawierać token umożliwiający odczytywanie następnej strony wyników. Token strony jest obecny w odpowiedzi tylko wtedy, gdy dostępnych jest więcej stron pojazdów dostawczych. Aby pobrać następną stronę zadań, użyj tokena strony z żądaniem, które jest poza tym identyczne z poprzednim żądaniem.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki Java gRPC, aby wyświetlić listę pojazdów wyświetlających w określonym regionie z określonym atrybutem. Odpowiedź udana może być nadal pusta. Oznacza to, że w określonym widocznym obszarze nie znajdują się już żadne pojazdy z określonym atrybutem.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Aby wyświetlić listę zadań w przeglądarce, wykonaj wywołanie HTTP REST do ListDeliveryVehicles:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Aby zastosować filtr do wymienionych zadań, uwzględnij parametr „filtra” adresu URL z wartością zapytania filtra ze zmianą znaczenia.
Nagłówek żądania musi zawierać pole Authorization z wartością Bearer <token>, gdzie <token> to token wydany przez fabrykę tokenów Fleet Engine.
Jeśli wyszukiwanie się powiedzie, treść odpowiedzi będzie zawierała dane o następującej strukturze:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Pomyślna odpowiedź może być nadal pusta. Oznacza to, że nie znaleziono żadnych pojazdów realizujących wyświetlenia, które spełniają określone zapytanie filtra i widoczny obszar.
Przykładowe polecenie curl:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Śledzenie floty
Aby włączyć śledzenie floty, skorzystaj z interfejsu Fleet Engine Deliveries API na 2 sposoby:
Preferowana: użyj biblioteki śledzenia floty w języku JavaScript. Biblioteka umożliwia wizualizację lokalizacji pojazdów i lokalizacji interesujących Cię, które są monitorowane we Fleet Engine. Zawiera komponent mapy JavaScript, który zastępuje standardowy obiekt google.maps.Map, oraz komponenty danych do łączenia się z Fleet Engine. Ten komponent umożliwia niestandardowe, animowane środowisko śledzenia floty z poziomu aplikacji internetowej lub mobilnej.
Zaimplementuj własne śledzenie floty w połączeniu z interfejsem Fleet Engine Deliveries API.
Kluczem jest wyszukiwanie zadań floty według identyfikatora śledzenia.
Logowanie
Możesz skonfigurować Fleet Engine tak, aby wysyłał logi RPC do Cloud Logging. Więcej informacji znajdziesz w artykule Logowanie.
Role i tokeny autoryzacji
Jak opisano w artykule Zarządzanie cyklem życia pojazdu i zadań oraz w uwagach dotyczących autoryzacji dla poszczególnych przypadków użycia, wywołania Fleet Engine wymagają uwierzytelniania za pomocą tokenów sieciowych JSON, które zostały podpisane przy użyciu danych logowania do konta usługi. Konta usługi używane do wystawiania tych tokenów mogą mieć jedną lub więcej ról, a każda rola może obejmować inny zestaw uprawnień.
Więcej informacji znajdziesz w artykule Uwierzytelnianie i autoryzacja.
Rozwiązywanie typowych problemów
W razie problemów zajrzyj do tych sekcji.
Odporność
Fleet Engine nie jest uważany za źródło wiarygodnych danych. Twoim obowiązkiem jest przywrócenie stanu systemu w razie potrzeby bez korzystania z Fleet Engine.
Utracony stan we Fleet Engine
Pracując z Fleet Engine, zaimplementuj klienty, tak aby system naprawiał się w przypadku awarii. Gdy na przykład Fleet Engine próbuje zaktualizować pojazd, może odpowiedzieć z komunikatem, że pojazd nie istnieje. Klient powinien następnie odtworzyć pojazd w nowym stanie. Ten problem zdarza się rzadko, ale upewnij się, że Twój system jest wystarczająco odporny, żeby na niego radzić.
W bardzo mało prawdopodobnym scenariuszu katastrofalnej awarii Fleet Engine konieczne może być odtworzenie większości pojazdów i zadań albo wszystkich zadań. Jeśli wskaźnik tworzenia stanie się zbyt wysoki, niektóre żądania mogą zostać ponownie nieudane z powodu problemów z limitami, ponieważ prowadzone są kontrole limitów, które mają na celu uniknięcie ataków typu DoS (odmowa usługi). W tym przypadku możesz zmniejszyć częstotliwość odtwarzania, używając strategii do ponowienia próby.
Utracony stan w aplikacji kierowcy
Jeśli aplikacja sterownika ulegnie awarii, musi odtworzyć bieżący stan w pakiecie SDK sterownika. Aplikacja powinna próbować odtworzyć zadania, aby upewnić się, że istnieją, i przywrócić ich obecny stan. Aplikacja powinna też ponownie utworzyć i jawnie ustawić listę przystanków w pakiecie SDK sterownika.
Najczęstsze pytania
Co się stanie, jeśli kierowca zatrzyma się w złej kolejności?
W takim przypadku najpierw zaktualizuj kolejność zadań, a następnie przejdź dalej w zwykły sposób, oznaczając przystanek, ukończenie zadania i inne szczegóły. Jeśli tego nie zrobisz, system może stać się niespójny, szacowany czas dotarcia na miejsce może się okazać nieprawidłowy i mogą zostać zgłoszone nieoczekiwane błędy.