Modeluj działania floty dla pierwszego i ostatniego etapu dostaw za pomocą interfejsu Fleet Engine Deliveries API. Możesz użyć tego interfejsu API za pomocą pakietu SDK sterownika na Androida i iOS lub bezpośrednio przez wywołania HTTP REST lub gRPC.
Konfiguracja początkowa
Interfejs Fleet Engine Deliveries API konfigurujesz w konsoli Google Cloud.
Informacje o czynnościach, które należy wykonać w konsoli, i o tym, jak utworzyć token sieciowy JSON na potrzeby autoryzacji, znajdziesz w sekcji Uwierzytelnianie i autoryzacja.
Szczegółowe informacje 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ę pojawiać podczas konfigurowania projektu. Konfigurację możesz sprawdzić na 2 sposoby:
Przetestuj 2 kluczowe elementy konfiguracji: podpisywanie tokenów autoryzacji i tworzenie pojazdów próbnych za pomocą narzędzia wiersza poleceń
gcloud. Szczegółowe informacje znajdziesz w przewodniku Weryfikowanie konfiguracji.Przetestuj konfigurację za pomocą przykładowych skryptów uwierzytelniania Fleet Engine.
Biblioteki klienta
Dla wygody programistów w porównaniu z nieprzetworzonym gRPC lub REST użyj bibliotek klienta w kilku popularnych językach programowania. Instrukcje 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 gRPC.
Struktury danych
Interfejs Fleet Engine Deliveries API wykorzystuje 2 struktury danych do modelowania odbioru i dostawy przesyłek:
- Pojazd służący do transportu przesyłki.
- Zadania dotyczące odbioru i dostawy przesyłki.
Korzystasz też z zadań, by modelować przerwy kierowcy i planować postoje na cały dzień.
Pojazdy dostawcze
Pojazdy transportowe pozwalają transportować przesyłki z magazynu do miejsca dostawy oraz z miejsca odbioru do magazynu. W niektórych przypadkach może też przetransportować przesyłkę bezpośrednio z miejsca odbioru do miejsca dostawy.
Użyj pakietu SDK sterownika, 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.
Lista zadań
Działania wykonywane przez pojazd w ciągu dnia możesz przypisać do rodzaju działania:
- W przypadku odbioru i dostawy przypisz zadania związane z wysyłką.
- W przypadku godzin niedostępności kierowców, na przykład wymaganych przerw, przypisz zadania związane z niedostępnością.
- W przypadku zadań niezwiązanych z jazdą samochodem w skrytkach lub w lokalizacjach klientów przypisz zaplanowane zadania zatrzymania.
Każde przypisane zadanie musi mieć unikalny identyfikator, ale zadania mogą mieć ten sam identyfikator śledzenia. Gdy Fleet Engine oblicza okresy czasu dotarcia na miejsce dla każdego zadania, używa wszystkich zadań i kolejności, w jakiej mają one wykonywać szacunki. Więcej informacji o identyfikatorach zadań znajdziesz w wytycznych dotyczących identyfikatorów zadań.
Aby tworzyć zadania we Fleet Engine, użyj Menedżera zadań pakietu SDK sterownika.
Zadania związane z dostawą
Utwórz zadania związane z wysyłką dotyczące odbioru i dostawy przesyłki i uwzględnij te informacje:
- Lokalizacja odbioru lub dostawy.
- Numer śledzenia lub identyfikator.
- Uzyskanie dodatkowego czasu na wykonanie zadania, zaparkowanie lub dojście do odpowiedniego miejsca.
- 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 załadowanie paliwa w pojeździe lub przerwy na odpoczynek kierowcy.
Utwórz zadanie związane z niedostępnością z tymi informacjami:
- Długość przerwy.
- Opcjonalnie lokalizacja przerwy. Nie musisz podawać konkretnej lokalizacji, ale dzięki temu będziesz uzyskiwać dokładniejsze informacje o szacowanym czasie dotarcia w ciągu dnia.
Więcej informacji można znaleźć w następujących tematach:
Android
iOS
Zadania zaplanowanego zatrzymania
Twórz zadania związane z zaplanowanymi postojami, aby uwzględnić przystanki potrzebne pojazdowi dostawczemu. Możesz na przykład utworzyć zadanie polegające na zatrzymaniu codziennego zaplanowanego przystanku odbioru w określonej lokalizacji niezależnie od innych dostaw i odbiorów w tym samym miejscu. Możesz też tworzyć zadania zaplanowanego zatrzymania odbioru ze skrzyń lub zatrzymania się w centrach serwisowych i punktach obsługi.
Więcej informacji można znaleźć w następujących tematach:
Android
iOS
Wskazówki na temat identyfikatora zadania
Podczas tworzenia identyfikatorów zadań przestrzegaj tych wytycznych dotyczących treści i formatu:
- Twórz unikalne identyfikatory zadań
- Nie ujawniaj żadnych informacji umożliwiających identyfikację osoby ani danych z czystym tekstem.
- Użyj prawidłowych ciągów Unicode.
- Użyj nie więcej niż 64 znaków.
- Nie wpisuj żadnych z tych znaków ASCII: „/”, „:”, „”,”, „?” ani „#”.
- Normalizuj zgodnie z postaci normalizacji Unicode C.
Oto kilka przykładów prawidłowych identyfikatorów zadań:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmowy2NzNkM2Jk
W poniższej tabeli znajdziesz 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ę osób i znaków: przecinków, kropek, dwukropków i ukośników. |
| JohnDoe-577b484da26f-Cupertino-SantaCruz | Narusza wymagania dotyczące informacji umożliwiających identyfikację osób. |
| 4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Narusza wymagania dotyczące informacji umożliwiających identyfikację osób i znaków: odstępów, przecinków i cudzysłowów. Nazwa koloru jest dłuższa niż 64 znaki. |
Więcej materiałów
Aby zobaczyć konkretne pola zawarte w każdej strukturze danych, zapoznaj się z dokumentacją API dotyczącą DeliveryVehicle (gRPC, REST) i Task (gRPC, REST).
Żywotność pojazdu
Obiekt DeliveryVehicle reprezentuje pojazd transportowy pierwszej lub ostatniej mili.
Tworzysz obiekt DeliveryVehicle za pomocą:
- Identyfikator projektu Google Cloud zawierającego konto usługi używane do wywoływania interfejsów Fleet Engine API.
- Identyfikator pojazdu należący do klienta.
Użyj unikalnych identyfikatorów dla każdego pojazdu. Nie używaj ponownie identyfikatora pojazdu, chyba że dla oryginalnego pojazdu nie ma żadnych aktywnych zadań.
Fleet Engine po 7 dniach automatycznie usuwa obiekty DeliveryVehicle, które nie zostały zaktualizowane za pomocą UpdateDeliveryVehicle. Aby sprawdzić,
czy pojazd jest w pobliżu:
- Zadzwoń pod numer
UpdateDeliveryVehicle. - Jeśli pojawi się błąd NOT_FOUND, wywołaj
CreateDeliveryVehicle, aby odtworzyć pojazd. Jeśli połączenie zostanie zwrócone, można go jeszcze zaktualizować.
Atrybuty pojazdu
Element DeliveryVehicle zawiera powtarzane pole DeliveryVehicleAttribute. Interfejs ListDeliveryVehicles API zawiera pole filter, które może ograniczać zwracane encje DeliveryVehicle do tych z określonymi atrybutami. DeliveryVehicleAttribute nie ma wpływu na kierowanie ruchu we 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.
Cykl życia zadania
We 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, w którym można śledzić postęp jego cyklu życia. Wartości zmieniają się 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 dostawczy nie minął jeszcze przypisany do tego zadania.
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 postojów. Spowoduje to automatyczne ustawienie stanu zadania na ZAMKNIĘTE.
Gdy pojazd związany z zadaniem się zatrzyma:
Zmień pole wyniku zadania na SUCCEEDED lub FAILED.
Podaj sygnaturę czasową zdarzenia.
Biblioteka śledzenia floty JavaScript wskazuje następnie wynik zadania, a stan zadania jest automatycznie ustawiany na ZAMKNIĘTE. Więcej informacji znajdziesz w artykule o śledzeniu floty za pomocą 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 istniejącym identyfikatorze, zwraca on błąd.
Uwaga: Fleet Engine nie obsługuje ręcznego usuwania zadań. Usługa automatycznie usuwa zadania po 7 dniach bez aktualizacji. Jeśli chcesz przechowywać dane zadań dłużej niż 7 dni, musisz wdrożyć tę funkcję samodzielnie.
Atrybuty zadania
Encja Task zawiera pole powtarzane pola TaskAttribute, które może zawierać wartość z jednego z 3 typów: ciągu znaków, liczby i wartości logicznej. Interfejs ListTasks API zawiera pole filter, które może ograniczać zwracane jednostki (Task) do tych z określonymi atrybutami. Atrybuty zadania 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ż atrybuty te mogą 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 ulepsza w Twoim imieniu.
Aby zarządzać cyklami ż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. Ten model pozwala Fleet Engine efektywnie zarządzać lokalizacją w czasie rzeczywistym. Funkcja ta wysyła lokalizację bezpośrednio do biblioteki śledzenia, za pomocą której możesz informować klientów o stanie zamówienia.
Załóżmy na przykład, że zachodzi taka sytuacja:
- Kierowca zbliża się do punktu dostawy. Aplikacja sterownika wysyła swoją lokalizację do Fleet Engine.
- Fleet Engine wysyła do biblioteki śledzenia lokalizację urządzenia, której aplikacja używa do informowania klienta o tym, że znajduje się w pobliżu paczki.
- Gdy kierowca zakończy dostawę, klika przycisk „Wysyłka dostarczona” w aplikacji kierowcy.
- Działanie „Dostawa dostarczona” powoduje wysłanie informacji do Twojego systemu backendu, który wykona niezbędne działania związane z weryfikacją i weryfikacją firmy.
- Twój system potwierdzi zadanie jako SUCCEEDED i zaktualizuje Fleet Engine za pomocą interfejsu Deliveries API.
Poniższy diagram przedstawia te procesy na poziomie ogólnym. Pokazuje też standardową relację między Twoim systemem, klientem i Fleet Engine.
Zarządzaj 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 wysyłanych przez klienta do Fleet Engine:
Wygeneruj token za pomocą roli konta usługi Niezaufany sterownik Fleet Engine Delivery.
Udostępnij aplikację sterownika z tokenem o ograniczonym zakresie. Ten zakres pozwala mu tylko aktualizować lokalizację urządzenia we Fleet Engine.
To podejście daje pewność, że połączenia 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 autoryzować aplikacje sterowników do wykonywania bezpośrednich aktualizacji Fleet Engine poza tymi, które są ograniczone do roli niezaufany kierowca, np. do niektórych aktualizacji zadań, możesz użyć roli Zaufany kierowca. Informacje o modelu, który korzysta z roli zaufanego sterownika, znajdziesz w sekcji Model zaufanego sterownika.
Więcej informacji o zastosowaniach ról niezaufanych i zaufanych sterowników znajdziesz w artykule Konfiguracja projektu Cloud.
Modelowanie dnia pracy
W tabeli poniżej opisujemy, jak może wyglądać dzień pracy w firmie transportowej lub logistycznej. Szczegóły Twojej firmy mogą się różnić, ale możesz zobaczyć, jak możesz przedstawić swój dzień pracy.
| Godzina | Aktywność | 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 dotyczące dostaw, odbioru, przerw i innych elementów. Możesz na przykład utworzyć zadanie dotyczące odbioru przesyłki, zadanie związane z dostawą przesyłki, zaplanowaną niedostępność lub zaplanowany postój.
Po ustaleniu kolejności paczek i kolejności ich dostarczania przypisz do pojazdu zadania. |
| Początek dnia | Kierowca zaczyna dzień w dworze, 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 one utworzone wcześniej, utwórz zadania dotyczące odbioru przesyłki, zaplanowaną niedostępność i zaplanowane przerwy. | |
| Kierowca opuszcza magazyn i zaczyna do wykonania kolejnej liczby zadań. | Przypisz do pojazdu wszystkie zadania lub ich podzbiór, zatwierdzając ich kolejność. | |
| Kierowca dostarcza przesyłkę. | Gdy dotrzesz na miejsce dostawy, wykonaj działania związane z przystankiem pojazdu. Po dostarczeniu przesyłki zamknij zadanie dostawy i opcjonalnie zapisz stan przesyłki i inne metadane. Po ukończeniu wszystkich zadań na przystanku i przed rozpoczęciem przejazdu do następnego przystanku wykonaj czynności związane z zatrzymaniem pojazdu i przejazdem pojazdem do następnego przystanku. | |
| Kierowca najeżdża na pojazd dostawczy, aby przekazać dodatkowe przesyłki do tego pojazdu. | Miejsce spotkań, w którym odbywa się przesiadka między pojazdem podającym a pojazdem dostawczym, powinno być modelowane jako zaplanowany przystanek.
Po przeniesieniu i zeskanowaniu przesyłki 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 ich kolejność. |
|
| Kierowca otrzymuje powiadomienie o prośbie o odbiór. | Po zaakceptowaniu prośby o odbiór utwórz zadanie dotyczące 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ę na lunch. | Jeśli z zadaniem dotyczącym niedostępności jest powiązana lokalizacja, należy ją traktować jak każde inne zadanie. Wykonuj działania związane z pojazdem na postój, zatrzymuje się i pojazdem w drodze do następnego przystanku.
W przeciwnym razie nie musisz niczego robić do końca przerwy. Aby usunąć zadanie, potwierdź kolejne i pozostałe zadania oraz zaktualizuj kolejność zadań. |
| Kierowca odbiera przesyłkę. | Jest to modelowane podobnie jak w przypadku postoju dostawy. Wykonuj działania związane z przyjazdem pojazdu i zakończeniem zadania oraz opcjonalnie zapisywanie stanu przesyłki i innych metadanych. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem przejazdu do następnego przystanku wykonaj czynności związane z zatrzymaniem pojazdu i przejazdem pojazdem do następnego przystanku. Uwaga: aby zapewnić prawidłowe płatności, wszystkie odbiory muszą mieć odpowiadające im zadanie dostawy. Jeśli tego dnia odbiór ma zostać dostarczony do innej lokalizacji znajdującej się na tej samej trasie kierowcy, zalecamy modelowanie tego zadania dostawy jako dowolnego innego zadania dostawy na trasie. Jeśli kierowca przynosi odbiór z powrotem do składu, zalecamy utworzenie zadania dostawy w miejscu docelowym. | |
| Kierowca zatrzymuje się, aby odebrać przesyłki ze skrzynki referencyjnej. | Sposób odbioru działa tak samo jak każdy inny przystanek. Wykonuj działania związane z pojazdem na postoju i zakończeniem zadania. Po wykonaniu wszystkich zadań na przystanku i rozpoczęciu przejazdu do następnego przystanku wykonaj działania związane z zatrzymaniem pojazdu i przejazdem pojazdem do następnego przystanku. | |
| Kierowca otrzymuje powiadomienie o skierowaniu przesyłki do innej lokalizacji. | Ustaw pierwotny stan zadania dostawy na UKOŃCZONO i utwórz nowe zadanie dostawy dla nowej lokalizacji dostawy. Więcej informacji znajdziesz w artykule Zmienianie trasy wysyłki. | |
| Kierowca próbował dostarczyć paczkę, ale mu się to nie udało. | Jest to modelowane podobnie do udanego zatrzymania dostarczania, co oznacza, że zadanie dostarczania zostało oznaczone jako ukończone. Wykonuj działania związane z przystankiem pojazdu. Jeśli nie uda się dostarczyć przesyłki, zamknij zadanie i opcjonalnie zapisz stan przesyłki oraz inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem przejazdu do następnego przystanku wykonaj czynności związane z zatrzymaniem pojazdu i przejazdem pojazdem do następnego przystanku. | |
| Kierowca został powiadomiony, że musi 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, zmieniając zamówienie w ramach zaplanowanej dostawy. | Zmień kolejność zadań. | |
| Kierowca decyduje się dostarczyć przesyłkę w złej kolejności. | Zaktualizuj kolejność zadań i kontynuuj w zwykły sposób. | |
| Kierowca dostarcza kilka przesyłek do jednej lokalizacji. | Ten model jest podobny do pojedynczego postoju dostawy. Po dotarciu do przystanku wykonaj działania związane z przystankiem pojazdu. Po dostarczeniu każdej przesyłki zamknij każde zadanie i opcjonalnie zapisz stan przesyłki i inne metadane. Po wykonaniu wszystkich zadań na przystanku i przed rozpoczęciem przejazdu do następnego przystanku wykonaj czynności związane z zatrzymaniem pojazdu i przejazdem pojazdem do następnego przystanku. | |
| Koniec dnia | Kierowca wraca do składu. | Jeśli kierowca wróci do magazynu z ładunkami odebranymi na jego trasie, musisz też utworzyć i zamknąć każdą paczkę jako zadanie dostawy, aby zapewnić prawidłowe naliczanie opłat. Możesz to zrobić, modelując magazyn tak jak w przypadku każdego innego przystanku. Jeśli magazyn nie jest używany jako postój na dostawę, możesz opcjonalnie wymodelować go jako zaplanowany przystanek. Opracowanie modelu przystanku pozwala kierowcom zobaczyć trasę z powrotem do zajazdu i uzyskać wgląd w 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, użyj jednego z tych sposobów:
- Użyj pakietu SDK sterownika – Android, iOS – najprostsza opcja.
- Użyj kodu niestandardowego, który jest przydatny, jeśli lokalizacje są przekazywane przez backend lub używasz urządzeń innych niż Android lub iOS.
Niezależnie od tego, jak będziesz aktualizować lokalizację pojazdu, Twój backend jest odpowiedzialny za aktualizowanie Fleet Engine, gdy pojazd dostawczy w drodze do postoju (w tym do stacji) i gdy dotrze na miejsce. Fleet Engine nie wykrywa tych zdarzeń automatycznie.
Miejsca postoju i dostawy pojazdów
Zatrzymanie pojazdu to miejsce, w którym pojazd dostawczy wykona zadanie związane z wysyłką lub inne zadanie. Może to być punkt dostępu, np. dok załadunkowy lub lokalizacja wytyczona po drodze.
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 na spacer.
Gdy 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 pojazdu. Następnie kierowca idzie z przystanku samochodowego do centrum handlowego, w którym znajduje się sklep. Jest to lokalizacja dostawy.
Aby zapewnić użytkownikom najlepsze wrażenia, zastanów się, w jaki sposób zadania wysyłki są przypisywane do postojów pojazdów. Pamiętaj też, że liczba postojów pozostałych pojazdów na realizację zadań wysyłki jest zgłaszana użytkownikowi, aby ułatwić mu śledzenie postępów przesyłki.
Jeśli na przykład kierowca dostarcza wiele dostaw do jednego budynku biurowego, rozważ przypisanie wszystkich zadań związanych z dostawą do jednego przystanku. Jeśli każde zadanie związane z dostawą jest przypisane do własnego przystanku, śledzenie przesyłki będzie mniej przydatne dla użytkowników, ponieważ śledzenie przesyłki będzie dostępne dopiero wtedy, gdy pojazd znajdzie się w ograniczonej liczbie postojów przed miejscem docelowym. Zrealizowanie wielu postojów w krótkim czasie nie daje użytkownikowi dużo czasu na śledzenie postępów dostawy.
Korzystanie z 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 Delivery Driver API, jak pokazano w tym przykładzie:
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));
}
});
Przykłady zastosowań
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 przyrostowych 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 SDK sterownika lub środowiska serwera za pomocą protokołu gRPC lub REST.
gRPC
Aby utworzyć nowy pojazd, wykonujesz wywołanie CreateDeliveryVehicle do Fleet Engine.
Atrybuty nowego pojazdu dostawczego możesz określić za pomocą obiektu CreateDeliveryVehicleRequest. Pamiętaj, że każda wartość podana w polu Name jest ignorowana 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 żadnych 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 za pomocą wywołania UpdateDeliveryVehicle.
Aby utworzyć pojazd bez ustawiania żadnych pól opcjonalnych, możesz pozostawić pole DeliveryVehicle nieskonfigurowane w CreateDeliveryVehicleRequest.
Poniższy przykład pokazuje, jak użyć biblioteki gRPC Java do utworzenia pojazdu:
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, wyślij 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 wypełnić te opcjonalne pola:
- atrybuty
- lastLocation
- Niestandardowy typ treści
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 żadnych 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 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}"
Tworzenie zadania odbioru przesyłki
Zadanie odbioru przesyłki możesz utworzyć za pomocą pakietu SDK sterownika lub środowiska serwera za pomocą gRPC lub REST.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java 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.
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ść Niestandardowy typ treści Type.PICKUP state State.OPEN trackingId Numer lub identyfikator używany do śledzenia przesyłki. plannedLocation Lokalizacja, w której zadanie ma zostać ukończone, w tym przypadku miejsce odbioru przesyłki. taskDuration Oczekiwany czas (w sekundach) potrzebny do odebrania przesyłki w miejscu 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.
Podczas tworzenia elementu wszystkie pozostałe pola są ignorowane. Fleet Engine zgłasza wyjątek, jeśli żądanie zawiera przypisany deliveryVehicleId. Przypisujesz zadania za pomocą 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
Utwórz zadanie dostawy za pomocą pakietu SDK sterownika lub środowiska serwera za pomocą gRPC lub REST.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java 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 ze środowiska serwera za pomocą gRPC lub REST, 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.
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ść Niestandardowy typ treści Type.DELIVERY state State.OPEN trackingId Numer lub identyfikator używany do śledzenia przesyłki. plannedLocation Lokalizacja, w której zadanie ma zostać ukończone, w tym przypadku lokalizacja dostawy tej przesyłki. taskDuration Oczekiwany czas (w sekundach) potrzebny na dostarczenie przesyłki do miejsca dostawy. 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.
Podczas tworzenia elementu wszystkie pozostałe pola są ignorowane. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator „shippingVehicleId”. Przypisujesz zadania za pomocą 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ń
Za pomocą gRPC lub REST możesz utworzyć grupę zadań ze środowiska serwera.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java utworzyć 2 zadania – jedno dla dostawy i jedno dla odbioru w tym samym miejscu:
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 są ustawione, muszą być identyczne z odpowiednimi polami na najwyższym poziomie BatchCreateTasksRequest. Zobacz, jak utworzyć zadanie dotyczące odbioru przesyłki i utworzyć zadanie dostawy, aby określić reguły weryfikacji dla każdego z nich.
Więcej informacji znajdziesz w dokumentacji interfejsu API usługi 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ść
Możesz utworzyć zadanie wskazujące na niedostępność (np. w przypadku przerw kierowcy lub uzupełnienia paliwa) za pomocą pakietu SDK kierowców albo środowiska serwera korzystającego z gRPC lub REST. Zaplanowane zadanie niedostępności nie może zawierać identyfikatora śledzenia. Opcjonalnie możesz podać lokalizację.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java utworzyć zadanie związane z 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 związane z niedostępnością 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. Jeśli nie masz identyfikatorów zadań w swoim systemie, możesz wygenerować uniwersalny unikalny identyfikator (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ść Niestandardowy typ treści Type.UNAVAILABLE state State.OPEN taskDuration Długość przerwy w sekundach. Pola opcjonalne:
Pole Wartość plannedLocation Lokalizacja przerwy, jeśli musi zostać wykonana w konkretnym miejscu.
Podczas tworzenia elementu wszystkie pozostałe pola są ignorowane. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator „shippingVehicleId”. Przypisujesz zadania za pomocą 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 Driver SDK albo w środowisku serwera za pomocą gRPC lub REST. Zaplanowane zadanie zatrzymania nie może zawierać identyfikatora śledzenia.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java 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ć zadanie zaplanowanego zatrzymania 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. Jeśli nie masz w systemie identyfikatorów zadań, możesz wygenerować unikalny identyfikator uniwersalny.
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ść Niestandardowy typ treści Type.SCHEDULED_STOP state State.OPEN plannedLocation Lokalizacja przystanku. taskDuration Oczekiwana długość zatrzymania w sekundach. Pola opcjonalne:
- Brak
Podczas tworzenia elementu wszystkie pozostałe pola są ignorowane. Fleet Engine zgłasza wyjątek,
jeśli żądanie zawiera przypisany identyfikator „shippingVehicleId”. Przypisujesz zadania za pomocą 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 należy wykonać zadanie. Jeśli na przykład przekazujesz odbiorcom informacje o czasie dostawy, możesz za pomocą tego pola uchwycić ten przedział czasu i wygenerować alerty lub przeanalizować wydajność po podróży.
Docelowy przedział czasu obejmuje godzinę rozpoczęcia i zakończenia i można go ustawić dla dowolnego typu zadania. Docelowy przedział czasu nie wpływa na zachowanie routingu.
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java ustawić okno czasowe 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
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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 wywołania do funkcji GetTaskTrackingInfo można kontrolować na podstawie poszczególnych zadań, ustawiając dla nich TaskTrackingViewConfig. Więcej informacji znajdziesz w sekcji Aktywne zadania związane z pojazdem. Można to zrobić przy tworzeniu lub aktualizowaniu zadania. Oto przykład aktualizowania zadania za pomocą tej konfiguracji:
gRPC
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java 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 ustawić okno konfiguracji widoku danych śledzenia zadań przez 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ń, która określa, które elementy danych są widoczne dla użytkowników w określonych okolicznościach. Pola opcjonalne:
- Brak
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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
Przypisujesz zadania do pojazdu dostawczego, aktualizując jego kolejność. Kolejność zadań dla pojazdu jest określana na podstawie listy postojów w pojeździe samochodowym. Każdemu przystankowi można przypisać jedno lub więcej zadań. Więcej informacji znajdziesz w artykule Aktualizowanie kolejności zadań.
Aby zmienić przesyłkę z jednego pojazdu na inny, zamknij pierwotne zadanie, a następnie utwórz je ponownie przed przypisaniem go do nowego pojazdu. Jeśli zaktualizujesz kolejność zadań, które jest już przypisane do innego pojazdu, pojawi się błąd.
Zaktualizuj kolejność zadań
Zadania związane z zamówieniami przypisanymi do pojazdu możesz aktualizować za pomocą pakietu SDK sterownika lub środowiska serwera. Nie używaj obu metod, aby uniknąć warunków rasowych i utrzymać jedno źródło wiarygodnych informacji.
Gdy zaktualizujesz kolejność zadań dla pojazdu, spowoduje to też:
- Przypisuje zadania, które są nowe w pojeździe.
- Zamyka wszystkie zadania, które zostały wcześniej przypisane do pojazdu, ale nie są uwzględnione w zaktualizowanej kolejności.
Aby zmienić dostawę z jednego pojazdu na inny, zamknij pierwotne zadanie, a następnie utwórz je ponownie przed przypisaniem go do nowego pojazdu. Jeśli zaktualizujesz kolejność zadań, 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 gRPC Java 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 we flocie, którego kolejność chcesz zaktualizować. Jest to identyfikator podany przy tworzeniu 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 ścieżki dla zadań w kolejności, w której mają być wykonywane. Pierwsze zadanie na liście jest wykonywane jako pierwsze. pozostałePojazdyJourneySegments[i].stop Przystanek podczas zadania i na liście. pozostałePojazdyJourneySegments[i].stop.plannedLocation Planowana lokalizacja przystanku. otherPojazdyJourneySegments[i].stop.tasks Lista zadań do wykonania na tym przystanku. remainingVehicleJourneySegments[i].stop.state State.NEW Pola opcjonalne:
- Brak
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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 jest w drodze do następnego przystanku
Usługa Fleet Engine musi być powiadamiana, gdy pojazd wyjdzie ze postoju lub rozpocznie nawigację. Możesz powiadomić Fleet Engine za pomocą pakietu SDK sterownika albo środowiska serwera przy użyciu gRPC lub REST. Nie używaj obu tych metod, aby uniknąć uwarunkowań rasowych i utrzymać jedno źródło wiarygodnych informacji.
gRPC
Poniższy przykład pokazuje, jak użyć biblioteki gRPC Java, aby powiadomić Fleet Engine o tym, że pojazd jest w drodze do następnego przystanku.
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, 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 we flocie, w przypadku którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany przy tworzeniu 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 stanami oznaczonymi jako State.NEW. Pierwszy przystanek na liście musi mieć stan oznaczony jako State.ENROUTE. Pola opcjonalne:
- Brak
Wszystkie 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 Driver SDK do aktualizowania lokalizacji pojazdu, możesz wykonać bezpośrednie wywołanie do Fleet Engine z informacją 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
Ten przykład pokazuje, jak za pomocą biblioteki gRPC Java zaktualizować lokalizację pojazdu we 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 w Twojej flocie lub identyfikator, którego lokalizację chcesz zaktualizować. Jest to identyfikator podany przy tworzeniu 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, w której pojazd znajdował się w tym miejscu. lastLocation.supplementalLocationSensor Powinno zawierać wartość 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 na przystanku
Usługa Fleet Engine musi otrzymać powiadomienie, gdy pojazd się zatrzyma. Możesz powiadomić Fleet Engine za pomocą pakietu SDK sterownika lub środowiska serwera za pomocą gRPC lub REST. Nie używaj obu tych metod, aby uniknąć uwarunkowań rasowych i utrzymać jedno źródło wiarygodnych informacji.
gRPC
Ten przykład pokazuje, jak użyć biblioteki gRPC Java do powiadomienia 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 przystanek 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 we flocie, w przypadku którego chcesz zaktualizować kolejność zadań. Jest to identyfikator podany przy tworzeniu 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, do którego dotrzesz, ma stan ustawiony jako State.ARRIVED, a po nim wyświetla się lista pozostałych przystanków z ich stanami oznaczonymi jako State.NEW. Pola opcjonalne:
- Brak
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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 kończy postój
Usługa Fleet Engine musi otrzymać powiadomienie, gdy pojazd się zatrzyma. Dzięki temu wszystkie zadania powiązane z przystankiem zostaną ustawione w stan ZAMKNIĘTE. Powiadomień Fleet Engine możesz użyć za pomocą pakietu SDK sterownika albo środowiska serwera za pomocą protokołu gRPC lub REST. Nie używaj obu tych metod, aby uniknąć sytuacji rasowych i zachować jedno źródło wiarygodnych informacji.
gRPC
Ten przykład pokazuje, jak użyć biblioteki gRPC Java do powiadamiania 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 ze środowiska serwera, wyślij 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 przy tworzeniu 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 przystanek nie powinien już być widoczny na liście pozostałych przystanków. Pola opcjonalne:
- Brak
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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ń jest stała. Możesz jednak modyfikować stan, wynik zadania, czas zakończenia zadania, lokalizację wyniku zadania i atrybuty, bezpośrednio aktualizując encję zadania. Jeśli na przykład zadanie nie zostało przypisane do pojazdu, możesz je zakończyć, bezpośrednio aktualizując 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 zakończeniu zatrzymania, na którym to zadanie jest wykonywane, lub usuń go z listy postojów. W tym celu możesz ustawić listę pozostałych przystanków, tak jak podczas aktualizowania kolejności zadań w przypadku konkretnego pojazdu.
Jeśli zadanie nie zostało jeszcze przypisane do pojazdu i musi zostać zamknięte, zmień je do stanu ZAMKNIĘTE. Nie możesz jednak ponownie otworzyć zadania ZAMKNIĘTE.
Zakończenie zadania nie oznacza powodzenia lub niepowodzenia. Sygnalizuje ona, że zadanie nie jest już uważane za wykonywane. W przypadku śledzenia floty ważne jest, aby wskazywać rzeczywisty wynik zadania, aby można było zobaczyć efekt dostarczenia.
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ć encję 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. Fleet Engine domyślnie ustawia ostatnią lokalizację pojazdu, o ile dostawca nie zastąpi jej ręcznie.
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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
Ustaw wynik działania i lokalizację wyników
Zakończenie zadania nie oznacza powodzenia lub niepowodzenia, wskazuje, że zadanie nie jest już uznawane za ukończone. W przypadku śledzenia floty ważne jest, aby wskazać rzeczywisty wynik zadania, co pozwoli uprzedzić wyniki dostawy i naliczyć za usługi odpowiednie płatności. Po skonfigurowaniu nie możesz zmienić wyniku zadania. Możesz jednak zmienić czas i lokalizację wyników zadania po ich ustawieniu.
Zadania, które mają stan ZAMKNIĘTE, mogą mieć wynik SUCCEEDED lub FAILED. Fleet Engine nalicza opłaty tylko za zadania dostarczania ze stanem SUCCEEDED.
Zaznaczając wynik zadania, Fleet Engine automatycznie wypełnia lokalizację wyniku zadania ostatnią znaną lokalizacją pojazdu. Możesz zastąpić to zachowanie.
gRPC
Podczas określania wyniku możesz ustawić lokalizację wyniku zadania. Ustawienie lokalizacji uniemożliwia Fleet Engine ustawienie jej domyślnej lokalizacji ostatniego pojazdu. Możesz też zastąpić lokalizację wyniku zadania ustawioną przez Fleet Engine później. Fleet Engine nigdy nie zastępuje podanej 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 zadania, jak i lokalizację wyniku zadania.
Poniższy przykład pokazuje, jak za pomocą biblioteki gRPC Java ustawić wynik zadania na SUCCEEDED i ustawić lokalizację, w której zostało ono ukończone:
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 Pola opcjonalne:
Pole Wartość taskOutcomeLocation Lokalizacja, w której zostało wykonane zadanie. Jeśli nie skonfigurujesz tej zasady, Fleet Engine ustawi ją domyślnie na ostatnią lokalizację pojazdu. taskOutcomeTime Sygnatura czasowa ukończenia zadania.
Podczas aktualizacji ignorowane są wszystkie pozostałe pola elementu.
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
zmiana trasy wysyłki,
Po utworzeniu zadania dostawy nie można zmienić jego zaplanowanej lokalizacji. Aby przekierować dostawę, zamknij zadanie dostawy bez określania wyniku, a następnie utwórz nowe zadanie ze zaktualizowaną zaplanowaną lokalizacją. Po utworzeniu nowego zadania przypisz je do tego samego pojazdu. Więcej informacji znajdziesz w artykule o zamykaniu zadania dostawy i przypisywaniu go.
Użyj podajnika i pojazdów dostawczych
Jeśli używasz pojazdów dostawczych do transportu przesyłek do pojazdów dostawczych w ciągu dnia, modeluj przesyłanie przesyłek jako zadanie zaplanowanego zatrzymania dla pojazdu dostawczego. Aby zapewnić dokładne śledzenie lokalizacji, zadanie dostawy przesyłki przypisuj tylko w przypadku przeniesionej przesyłki po załadowaniu jej do pojazdu dostawy. Więcej informacji znajdziesz w artykule o zaplanowanym przystanku.
Przechowuj stan przesyłki i inne metadane
Po zakończeniu zadania dostawy jego stan i wynik są rejestrowane w zadaniu. Możesz jednak zaktualizować inne metainformacje związane z dostawą. Aby przechowywać inne metainformacje, do których można 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 o życiu zadania.
Wyszukiwanie pojazdu
Pojazd możesz wyszukać za pomocą pakietu SDK sterownika albo środowiska serwera przy użyciu gRPC lub REST.
gRPC
Z przykładu poniżej dowiesz się, jak wyszukać pojazd przy użyciu biblioteki gRPC Java:
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, wyślij 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óry chcesz wyszukać.
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ę uda, treść odpowiedzi będzie zawierała encję 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
Poniższy przykład pokazuje, jak użyć biblioteki gRPC Java 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 ze środowiska serwera, wyślij 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ę uda, 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 zadaniu dostawy według identyfikatora śledzenia,
Informacje o zadaniach floty możesz wyszukiwać na następujące sposoby, z których każdy ma inne zastosowanie:
- według identyfikatora zadania: opcja używana przez użytkowników takich jak operatorzy floty, którzy mają dostęp do pełnego widoku danych zadań.
- za pomocą identyfikatora śledzenia: używany przez oprogramowanie klienckie do przekazywania użytkownikowi ograniczonych informacji, na przykład o tym, kiedy przesyłka powinna dotrzeć do użytkownika.
W tej sekcji omawiamy wyszukiwanie informacji o zadaniach według identyfikatora śledzenia. Jeśli chcesz wyszukać zadanie według identyfikatora zadania, zapoznaj się z sekcją Wyszukiwanie zadania.
Aby wyszukać informacje według identyfikatora śledzenia, możesz użyć jednej z tych opcji:
Wymagania dotyczące wyszukiwania
Informacje o dostawie dostarczane przez identyfikator śledzenia są zgodne z regułami widoczności określonymi w artykule Kontrolowanie widoczności śledzonych lokalizacji.
Użyj Fleet Engine do wyszukania informacji o dostawie według identyfikatora śledzenia. Pakiet SDK sterowników nie obsługuje wyszukiwania informacji według identyfikatora śledzenia. Aby to zrobić we Fleet Engine, używasz środowiska serwera lub przeglądarki.
Używaj możliwie najwęższego tokena, aby ograniczyć zagrożenia dla bezpieczeństwa. Jeśli na przykład korzystasz z tokena klienta dostawy, każde wywołanie interfejsu Fleet Engine Deliveries API zwraca tylko informacje istotne dla tego użytkownika, takie jak firma kurierska lub odbiorca przesyłki. Pozostałe informacje w odpowiedziach zostaną usunięte. Więcej informacji o tokenach znajdziesz w artykule o tworzeniu tokena internetowego JSON (JWT) na potrzeby autoryzacji.
Wyszukiwania w języku Java używające gRPC
Z przykładu poniżej dowiesz się, jak za pomocą biblioteki gRPC Java wyszukać 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;
}
Wyszukiwania przy użyciu protokołu HTTP
Aby wyszukać zadanie dostawy w przeglądarce, wyślij 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ę uda, 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 SDK sterowników nie obsługuje wyświetlania listy zadań.
Wyświetlanie listy zadań wymaga szerokiego dostępu do zadań. Zadania z listą są przeznaczone tylko dla zaufanych użytkowników. Używaj tokenów uwierzytelniania floty usług Delivery Fleet Reader lub Delivery Super User Authentication for Delivery podczas tworzenia żądań zadań związanych z listą.
Na liście zadań nie ma tych pól:
- 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 w dokumentacji AIP-160. Na tej liście 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
- Niestandardowy typ treści
Użyj tych formatów pól zgodnych z propozycjami ulepszenia interfejsu API Google:
| Typ pola | Format | Przykład |
|---|---|---|
| sygnatura czasowa, | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
| Czas działania | Liczba sekund, po których następuje s |
task_duration = 120s |
| Typ wyliczeniowy | 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, na liście będą wyświetlane 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 jest większa niż określony rozmiar strony. Jeśli nie ma podanego 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 umożliwiający odczytanie następnej strony wyników. użyć tokena strony z żądaniem, które jest identyczne z poprzednim żądaniem pobrania następnej strony zadań. Gdy zwrócony token strony jest pusty, nie można pobrać więcej zadań.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki gRPC Java do wyświetlania listy zadań dla parametru „deliveryVehicleId” i atrybutu zadania. Pomyślna odpowiedź może być nadal pusta. Pusta odpowiedź oznacza, że żadne zadania nie są powiązane z podanym adresem DeliveryVehicleId.
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, wyślij 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 adresu URL „filtr” z zapytaniem o zmianę znaczenia w adresie URL jako jego wartością.
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ę uda, 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 dostawy ze środowiska serwera lub przeglądarki. Pakiet SDK kierowcy nie obsługuje wyświetlania informacji o samochodach dostawczych.
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 Czytnika floty usług lub tokenów uwierzytelniania superużytkowników dostarczania podczas tworzenia żądań pojazdów dostarczających listy.
W wymienionych pojazdach dostawczych usunęliśmy te pola ze względu na ich wpływ na rozmiar odpowiedzi:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Listę pojazdów dostarczających 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 móc wysyłać zapytania obejmujące wiele atrybutów, złącz zapytania za pomocą logicznych operatorów AND i OR, jak w przypadku attributes.key1 = value1 AND
attributes.key2 = value2. Pełny opis składni zapytań filtrów znajdziesz na stronie 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 współrzędnych: high (północny wschód) i low (południowo-zachodniego) szerokości i długości geograficznej. Żądania są odrzucane, jeśli obejmują dużą szerokość geograficzną, która jest geograficznie mniejsza niż niska.
Listy pojazdów obsługujących dostawę są domyślnie podzielone na strony przy użyciu uzasadnionego rozmiaru strony. Jeśli podasz rozmiar strony, żądanie zwróci tylko liczbę pojazdów określoną w limicie lub ich mniej. Jeśli żądany rozmiar strony przekracza wewnętrzną wartość maksymalną, stosowana jest wartość wewnętrzna. Domyślny i maksymalny rozmiar strony to po 100 pojazdów.
Lista pojazdów dostarczających może zawierać token służący do odczytu następnej strony wyników. Token strony pojawia się 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 identyczne z poprzednim żądaniem.
gRPC
Z przykładu poniżej dowiesz się, jak użyć biblioteki gRPC Java do wyświetlania listy pojazdów dostawy w określonym regionie z określonym atrybutem. Odpowiedź z powodzeniem może być nadal pusta. Oznacza to, że żadne pojazdy z określonym atrybutem nie znajdują się już w określonym widocznym obszarze.
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, wyślij wywołanie HTTP REST do ListDeliveryVehicles:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Aby zastosować filtr do wymienionych zadań, dołącz parametr adresu URL „filtr” z zapytaniem o zmianę znaczenia w adresie URL jako jego wartością.
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ę uda, 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 dostarczających danych spełniających kryteria filtra i widocznych obszarów.
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
Interfejs Fleet Engine Deliveries API umożliwia śledzenie floty na 2 sposoby:
Preferowane: korzystaj z biblioteki śledzenia floty w języku JavaScript. Biblioteka umożliwia wizualizację lokalizacji pojazdów i wyszukiwanych lokalizacji śledzonych 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 dostosowywane, animowane środowisko śledzenia floty z poziomu aplikacji internetowej lub mobilnej.
Zaimplementuj własne śledzenie floty razem 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 o rejestrowaniu.
Role i tokeny autoryzacji
Jak opisano w sekcji Zarządzanie cyklem życia pojazdu i zadania 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 za pomocą danych logowania konta usługi. Konta usługi używane do wystawiania tych tokenów mogą mieć 1 lub więcej ról, a każda z nich może mieć inny zestaw uprawnień.
Więcej informacji znajdziesz w artykule na temat uwierzytelniania i autoryzacji.
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. W razie potrzeby musisz przywrócić stan systemu bez korzystania z Fleet Engine.
Utracony stan we Fleet Engine
Pracując z Fleet Engine, zaimplementuj klienty tak, aby system sam się naprawiał w przypadku awarii. Gdy na przykład Fleet Engine próbuje zaktualizować pojazd, może w odpowiedzi wysłać komunikat o błędzie informujący o tym, że pojazd nie istnieje. Klient powinien następnie odtworzyć pojazd w nowym stanie. Choć ten problem rzadko występuje, upewnij się, że Twój system jest wystarczająco odporny, aby go rozwiązać.
W skrajnie mało prawdopodobnym scenariuszu katastrofalnej awarii Fleet Engine musisz odtworzyć większość pojazdów i zadań (lub wszystkie). Jeśli częstotliwość tworzenia zostanie zbyt duża, niektóre żądania mogą zostać ponownie nieudane z powodu problemów z limitami, ponieważ prowadzone są kontrole limitów, aby uniknąć ataków typu DoS. W tym przypadku spowolnij tempo regeneracji, stosując strategię ponawiania prób.
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 sprawdzić, czy istnieją i przywrócić ich obecny stan. Aplikacja powinna też odtworzyć i jawnie ustawić listę zatrzymania dla pakietu Driver SDK.
Najczęstsze pytania
Co się stanie, jeśli kierowca zatrzyma się z powodu nieprawidłowego działania?
W takim przypadku najpierw zaktualizuj kolejność zadań, a następnie kontynuuj w zwykły sposób, oznaczając przyjazd na przystanku, 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 być nieprawidłowy i mogą zostać zgłoszone nieoczekiwane błędy.