Interfejs Fleet Engine On-demand Rides and Deliveries API umożliwia zarządzanie podróżami i stanem pojazdu w aplikacjach związanych z podróżą i postępem realizacji zamówień. Obsługuje transakcje między pakietem Driver SDK, pakietem Consumer SDK i usługą backendu, która może komunikować się z Fleet Engine za pomocą wywołań gRPC lub REST.
Wymagania wstępne
Na potrzeby programowania zainstaluj pakiet SDK Cloud (gcloud) i uwierzytelnij go w projekcie.
powłoka
gcloud auth login
Powinien wyświetlić się komunikat o powodzeniu, taki jak:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Sprawdź, czy interfejsy API usługi Fleet Engine w rozwiązaniu na żądanie dotyczące przejazdów i dostaw na żądanie są odpowiednio skonfigurowane.
powłoka
gcloud --project=project-id services enable fleetengine.googleapis.com
Jeśli po użyciu tego polecenia pojawi się błąd, skontaktuj się z administratorem projektu i przedstawicielem zespołu pomocy Google, aby uzyskać dostęp.
Logowanie
Fleet Engine może zapisywać komunikaty logów dotyczące otrzymywanych wywołań interfejsu API w logach Google Cloud Platform. Aby dowiedzieć się, jak odczytywać i analizować logi, zapoznaj się z dokumentacją Cloud Logging.
Logowanie może być domyślnie wyłączone w przypadku projektów utworzonych przed 10 lutego 2022 r. Więcej informacji znajdziesz w dokumentacji dotyczącej logowania.
Biblioteki klienta
Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te biblioteki ułatwią programistom obsługę nieprzetworzonych plików REST lub gRPC. Instrukcje uzyskiwania bibliotek klienta dla aplikacji serwerowej znajdziesz w artykule Biblioteki klienta.
W przykładach w Javie w tej dokumentacji zakładamy, że znasz gRPC.
Uwierzytelnianie i autoryzacja
Możliwości zapewniane przez proces Podróży i Postęp realizacji zamówienia możesz skonfigurować w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON, które zostały podpisane za pomocą kont usługi utworzonych w Cloud Console.
Konfigurowanie projektu Cloud
Aby skonfigurować projekt w chmurze, najpierw go utwórz, a potem utwórz konta usługi.
Aby utworzyć projekt Google Cloud:
- Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
- Za pomocą panelu interfejsów API i usług włącz interfejs Local Rides and Deliveries API.
Konta usługi są powiązane z co najmniej 1 rolą. Służą do tworzenia tokenów sieciowych JSON, które przyznają różne zestawy uprawnień w zależności od ról. Aby zmniejszyć ryzyko nadużyć, można zwykle utworzyć wiele kont usługi, każde z minimalnym wymaganym zestawem ról.
Działania związane z podróżą i zamówieniem są powiązane z tymi rolami:
Rola | Opis |
---|---|
Użytkownik pakietu SDK Fleet Engine roles/fleetengine.consumerSdkUser |
Daje uprawnienia do wyszukiwania pojazdów oraz pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z urządzeń mobilnych w ramach wspólnych przejazdów lub dostawy dla klientów indywidualnych. |
Użytkownik pakietu SDK Fleet Engine Driver
roles/fleetengine.driverSdkUser |
Przyznaje uprawnienia do aktualizowania lokalizacji i tras pojazdów oraz pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z urządzeń mobilnych z aplikacją do wspólnych przejazdów lub aplikacji kierowcy. |
Administrator Fleet Engine na żądanie
roles/fleetengine.ondemandAdmin |
Przyznaje uprawnienia do odczytu i zapisu wszystkich zasobów pojazdu i podróży. Podmioty zabezpieczeń z tą rolą nie muszą używać tokenów JWT i powinny używać domyślnych danych logowania aplikacji. Niestandardowe żądania JWT są ignorowane. Ta rola powinna być ograniczona do zaufanych środowisk (backendu klienta). |
roles/fleetengine.serviceSuperUser |
Przyznaje uprawnienia do wszystkich interfejsów API związanych z pojazdami i podróżami. Tokeny wygenerowane przez konto usługi z tą rolą są zwykle używane z serwerów backendu. Ta rola została wycofana. Wolę roles/fleetengine.ondemandAdmin . |
Możesz na przykład utworzyć konto usługi dla każdej z 3 ról i przypisać im odpowiednie role.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Pakiety sterowników i pakietów SDK dla klientów indywidualnych opierają się na tych standardowych rolach.
Możesz też utworzyć role niestandardowe, które pozwalają połączyć w grupie dowolny zestaw uprawnień. Pakiety SDK sterowników i klientów będą wyświetlać komunikaty o błędach za każdym razem, gdy brakuje wymaganych uprawnień. Dlatego zdecydowanie zalecamy korzystanie ze standardowego zestawu ról przedstawionych powyżej zamiast używania ról niestandardowych.
Jeśli musisz utworzyć tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi pozwoli im tworzyć tokeny za pomocą narzędzi wiersza poleceń gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Gdzie my-user@example.com
to adres e-mail używany do uwierzytelniania w gcloud (gcloud auth list
--format='value(account)'
).
Biblioteka uwierzytelniania Fleet Engine
Fleet Engine używa tokenów sieciowych JSON (JWT) do ograniczania dostępu do interfejsów Fleet Engine API. Nowa biblioteka uwierzytelniania Fleet Engine, dostępna w GitHub, upraszcza tworzenie tokenów JWT Fleet Engine i bezpiecznie je podpisuje.
Biblioteka zapewnia te korzyści:
- Upraszcza proces tworzenia tokenów Fleet Engine.
- Udostępnia mechanizmy podpisywania tokenów inne niż korzystające z plików danych logowania (np. podszywanie się pod konto usługi).
- Dołącza podpisane tokeny do żądań wychodzących wysyłanych z pośrednika gRPC lub klienta GAPIC.
Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji
Jeśli nie używasz biblioteki uwierzytelniania Fleet Engine, tokeny internetowe JSON (JWT) muszą być utworzone bezpośrednio w bazie kodu. Wymaga to dogłębnej wiedzy o tokenach JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.
Tokeny internetowe JSON (JWT) we Fleet Engine zapewniają uwierzytelnianie przez krótki czas i sprawiają, że urządzenia mogą modyfikować wyłącznie pojazdy, podróże i zadania, do których są uprawnione. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera informacje takie jak klucz prywatny do użycia (uzyskany z kont usługi) i algorytm szyfrowania. Sekcja deklaracji zawiera informacje takie jak czas utworzenia tokena, czas życia tokenów, usługi, do których uzyskał dostęp, i inne informacje dotyczące autoryzacji, np. identyfikator pojazdu.
Sekcja nagłówka JWT zawiera te pola:
Pole | Opis |
---|---|
alg | Algorytm, który ma być używany. „RS256”. |
typ | Typ tokena. JWT. |
dziecko | Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` w pliku JSON konta usługi. Pamiętaj, aby użyć klucza z konta usługi o odpowiednim poziomie uprawnień. |
Sekcja deklaracji JWT zawiera te pola:
Pole | Opis |
---|---|
Iss | Adres e-mail konta usługi. |
zast. | Adres e-mail konta usługi. |
Aud | Twoje konto usługi to SERVICE_NAME, w tym przypadku https://fleetengine.googleapis.com/ |
Iat | Sygnatura czasowa określająca, kiedy token został utworzony, wyrażona w sekundach, które upłynęły od 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa przypada w zbyt odległej przeszłości lub w przyszłości, serwer może zgłosić błąd. |
exp | Sygnatura czasowa wygaśnięcia tokena podana w sekundach, które upłynęły od 00:00:00 czasu UTC, 1 stycznia 1970 r. Żądanie nie zostanie zrealizowane, jeśli sygnatura czasowa będzie wybiegać więcej niż godzinę w przyszłość. |
autoryzacja | W zależności od przypadku użycia może zawierać parametr „vehicleid” lub „tripid”. |
Utworzenie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu umożliwiające tworzenie i podpisywanie tokena JWT znajdziesz w artykule Autoryzacja konta usługi bez OAuth. Następnie możesz dołączyć podpisany token do wywołań gRPC lub innych metod używanych do uzyskiwania dostępu do Fleet Engine.
Żądania JWT
Podczas tworzenia ładunku JWT dodaj w sekcji autoryzacji dodatkową deklarację z kluczem vehicleid
lub tripid
ustawionym na wartość identyfikatora pojazdu lub identyfikatora podróży, którego dotyczy wywołanie.
Pakiet Driver SDK zawsze używa twierdzenia vehicleid
, niezależnie od tego, czy odbywa się podczas podróży, czy w pojeździe. Backend Fleet Engine upewnia się, że pojazd jest powiązany z żądaną podróżą przed wykonaniem modyfikacji.
Pakiet SDK klienta zawsze używa roszczenia tripid
.
Dostawca wspólnych przejazdów lub dostawca usług dostawy powinien użyć znaku vehicleid
lub tripid
ze znakiem „*”, aby wyszukać wszystkie pojazdy i podróże. Pamiętaj, że token JWT może zawierać oba tokeny, nawet jeśli nie jest wymagane, ponieważ może to uprościć implementację podpisywania tokenów.
Przypadki użycia JWT
Poniżej znajdziesz przykładowy token dla opcji Serwer dostawcy:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Poniżej znajdziesz przykładowy token dla aplikacji konsumenta:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Poniżej znajdziesz przykładowy token dla aplikacji sterownika:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- W polu
kid
w nagłówku podaj identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w poluprivate_key_id
w pliku JSON konta usługi. - W polach
iss
isub
podaj adres e-mail konta usługi. Tę wartość znajdziesz w poluclient_email
w pliku JSON konta usługi. - W polu
aud
wpisz https://SERVICE_NAME/. - W polu
iat
użyj sygnatury czasowej utworzenia tokena określonej jako czas, który upłynął od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa lub w przyszłości, serwer może zgłosić błąd. - W polu
exp
użyj sygnatury czasowej wygaśnięcia tokena określonej w sekundach od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Maksymalna dozwolona wartość toiat
+ 3600.
Podczas podpisywania tokena JWT, który ma być przekazany na urządzenie mobilne, w roli pakietu SDK sterownika lub pakietu SDK dla klienta użyj konta usługi. W przeciwnym razie urządzenie mobilne będzie mogło zmienić stan, w którym nie powinno.
Podobnie w przypadku podpisywania tokena JWT, który ma być używany w wywołaniach z podwyższonymi uprawnieniami, używaj konta usługi z rolą superużytkownika. W przeciwnym razie operacja się nie powiedzie.
Generowanie tokena JWT na potrzeby testowania
Generowanie tokenów z terminala może być pomocne podczas testowania.
Aby można było wykonać te czynności, Twoje konto użytkownika musi mieć przypisaną rolę twórcy tokenów konta usługi:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Utwórz nowy plik o nazwie unsigned_token.json
z poniższą zawartością. Właściwość iat
to bieżący czas wyrażony w sekundach po zakończeniu epoki. Aby go pobrać, uruchom w terminalu polecenie date +%s
. Właściwość exp
to czas do wygaśnięcia (w sekundach) po epoki. Aby go obliczyć, dodaj do wartości iat
wartość 3600. Czas wygaśnięcia nie może przekraczać godziny w przyszłości.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
Następnie uruchom to polecenie gcloud, aby podpisać token w imieniu swojego konta usługi SuperUser:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
W pliku signed_token.jwt
powinien być teraz przechowywany podpisany token JWT zakodowany w standardzie Base64. Token będzie ważny przez następną godzinę.
Możesz teraz przetestować token, uruchamiając polecenie curl
w punkcie końcowym REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Pojazdy i ich cykl życia
Pojazd to podmiot reprezentujący parę kierowca–pojazd. Obecnie nie można śledzić oddzielnie kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawca usług dostawy tworzy pojazd przy użyciu identyfikatora dostawcy (musi być taki sam jak identyfikator projektu w projekcie Google Cloud, który zawiera konto usługi używane do wywoływania interfejsów Fleet Engine API) oraz identyfikatora pojazdu należącego do dostawcy wspólnych przejazdów lub dostawcy dostawy.
Pojazd, który nie został zaktualizowany przez UpdateVehicle
po 7 dniach, zostanie automatycznie usunięty. Aby utrzymać dostępność pojazdu we Fleet Engine, zalecamy regularne aktualizowanie jego lokalizacji. Aktualizacje większości innych pól w elemencie Vehicle
także wydłużą okres ich życia, o ile nowa wartość pola będzie się różnić od wartości dotychczasowej.
UWAGA: niektóre pola w elemencie Vehicle
, na przykład device_settings
, zawierają wyłącznie informacje debugowania, które nie są zachowywane przez Fleet Engine. Zaktualizowanie ich nie przedłuża żywotności elementu Vehicle
.
Wywołanie funkcji CreateVehicle
z podaniem identyfikatora dostawcy i identyfikatora pojazdu, które już istnieje, powoduje błąd. W przypadku pojazdów, które nie są często aktualizowane, można rozwiązać 2 sposoby: częste wywoływanie funkcji CreateVehicle
z oczekiwaną parą identyfikatora dostawcy i identyfikatora pojazdu i odrzucanie błędu, jeśli pojazd już istnieje, lub wywołanie funkcji CreateVehicle
po wystąpieniu UpdateVehicle
zwraca błąd NOT_FOUND
.
Aktualizacje lokalizacji pojazdu
Aby uzyskać najlepszą wydajność w usłudze Fleet Engine, udostępnij jej strumień aktualizacji lokalizacji pojazdu. Zaktualizuj informacje na jeden z tych sposobów:
- Użyj pakietu Driver SDK – Android, iOS – najprostsza opcja.
- Użyj kodu niestandardowego – przydaje się to, gdy lokalizacje są przekazywane przez Twój backend albo jeśli korzystasz z urządzeń innych niż Android lub iOS.
Rodzaj pojazdu
Element Pojazd zawiera wymagane pole VehicleType
, które zawiera wyliczenie Category
, które można określić jako AUTO
, TAXI
, TRUCK
, TWO_WHEELER
, BICYCLE
lub PEDESTRIAN
. Typ pojazdu może służyć jako kryteria filtrowania w usługach SearchVehicles
i ListVehicles
.
Przy ustalaniu tras dla pojazdów używany jest odpowiedni atrybut RouteTravelMode
, jeśli kategoria jest ustawiona na AUTO
, TWO_WHEELER
, BICYCLE
lub PEDESTRIAN
.
Jeśli kategoria jest ustawiona na TAXI
lub TRUCK
, routing jest traktowany tak samo jak tryb AUTO
.
Atrybuty pojazdu
Element Pojazd zawiera powtarzane pole VehicleAttribute
. Te atrybuty nie są interpretowane przez Fleet Engine. Interfejs API SearchVehicles
zawiera pole, które wymaga dopasowania Vehicles
, aby zawierał wszystkie uwzględnione atrybuty ustawione na określoną wartość.
Pamiętaj, że pole atrybutu jest uzupełnieniem kilku innych obsługiwanych pól w komunikacie Vehicle
, takich jak vehicle_type
i supported_trip_types
.
Pozostałe punkty na trasie pojazdu
Element Pojazd zawiera powtarzane pole TripWaypoint
(RPC | REST) o nazwie waypoints
(RPC | REST).
To pole zawiera pozostałe punkty na trasie przejazdu w kolejności, w jakiej pojazd do nich dociera. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je, gdy podróże zmieniają stan.
Te punkty pośrednie można zidentyfikować za pomocą pól TripId
i WaypointType
.
Zwiększanie możliwości dopasowania pojazdu
Za dopasowywanie żądań podróży do pojazdów odpowiadają zwykle usługi wspólnych przejazdów lub dostawców dostaw. Usługa może wykorzystać atrybuty pojazdu, aby uwzględnić pojazd w większej liczbie wyszukiwań. Dostawca może na przykład wdrożyć zestaw atrybutów odpowiadających poziomom bonusów lub możliwości zapewnianych przez pojazd. Na przykład trzy poziomy mogą być zbiorem atrybutów z wartościami logicznymi: is_bronze_level
, is_silver_level
i is_gold_level
. Pojazd może kwalifikować się
do tych 3 opcji. Gdy Fleet Engine otrzyma żądanie podróży wymagającej umiejętności na poziomie srebrnym, wyszukiwanie będzie obejmować ten pojazd.
Użycie atrybutów w ten sposób obejmuje pojazdy o różnych możliwościach.
Atrybuty pojazdu można aktualizować na 2 sposoby. Jednym z nich jest UpdateVehicle
API. Gdy używasz tego interfejsu API, cały zestaw atrybutów pojazdu ma ustawioną tę wartość. Nie można zaktualizować tylko jednego atrybutu.
Drugą metodą jest interfejs API UpdateVehicleAttributes
. Ta metoda wymaga tylko aktualizacji atrybutów. Atrybuty zawarte w żądaniu zostaną ustawione na nową wartość lub dodane. Nieokreślone atrybuty nie ulegną zmianie.
INSTRUKCJA: tworzenie pojazdu
Dla każdego pojazdu, który ma być śledzony we flocie, należy utworzyć element Vehicle
.
Użyj punktu końcowego CreateVehicle
z CreateVehicleRequest
, by utworzyć pojazd.
provider_id
obiektu Vehicle
musi być identyfikatorem projektu (np. my-on-demand-project) projektu Google Cloud zawierającego konta usługi, które będą używane do wywoływania Fleet Engine. Pamiętaj, że chociaż wiele kont usług ma dostęp do platformy Fleet Engine dla tego samego dostawcy usług wspólnych lub dostawcy usług dostawy, Fleet Engine nie obsługuje obecnie kont usługi z wielu projektów Google Cloud uzyskujących dostęp do tego samego Vehicles
.
Vehicle
można utworzyć w stanie OFFLINE
lub ONLINE
. Jeśli została utworzona ONLINE
, może zostać natychmiast zwrócona w odpowiedzi na zapytania SearchVehicles
.
Początkowe wywołanie last_location
może zostać uwzględnione w wywołaniu CreateVehicle
.
Chociaż jest to dozwolone, nie należy tworzyć Vehicle
w stanie ONLINE
bez last_location
.
Szczegółowe informacje o polu typu pojazdu znajdziesz w sekcji Typy pojazdów.
Szczegółowe informacje o polu atrybutów znajdziesz w sekcji Atrybuty pojazdu.
Wartość zwrócona z metody CreateVehicle
to utworzony element Vehicle
.
Przykład
powłoka
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Więcej informacji znajdziesz w dokumencie providers.vehicles.create.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Logi Google Cloud Platform dotyczące tworzenia pojazdu
Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego CreateVehicle
. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle
. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Vehicle
.
powłoka
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Powinien zostać wydrukowany rekord podobny do tego:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Powiadomienia Cloud Pub/Sub dotyczące tworzenia pojazdu
Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub po utworzeniu nowego pojazdu. Aby je otrzymywać, postępuj zgodnie z instrukcjami opisanymi tutaj.
INSTRUKCJA: aktualizowanie lokalizacji pojazdu
Jeśli nie używasz pakietu Driver SDK do aktualizowania lokalizacji pojazdu, możesz nawiązać bezpośrednie wywołanie do Fleet Engine, podając lokalizację pojazdu. W przypadku każdego aktywnego pojazdu Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę, a nie częściej niż co 5 sekund. Te aktualizacje wymagają uprawnień tylko użytkowników pakietu Fleet Engine Driver SDK.
Przykład
powłoka
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
Patrz: providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
INSTRUKCJA: aktualizowanie innych pól dotyczących pojazdu
Aktualizacje innych atrybutów stanu pojazdu odbywają się rzadziej niż aktualizacje pozycji. Aktualizacje atrybutów innych niż last_location
wymagają uprawnień superużytkownika Fleet Engine.
UpdateVehicleRequest
zawiera pole update_mask
wskazujące pola, które należy zaktualizować. Działanie tego pola jest takie samo jak w dokumentacji Protobuf dotyczącej masek pól.
Jak wspomnieliśmy w atrybutach pojazdu, aktualizacja pola attributes
wymaga zapisania wszystkich atrybutów. Nie można zaktualizować wartości tylko jednej pary klucz-wartość w wywołaniu UpdateVehicle
. Aby zaktualizować wartości określonych atrybutów, można użyć interfejsu API UpdateVehicleAttributes
.
Przykład
W tym przykładzie włączona jest funkcja back_to_back
.
powłoka
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Patrz: providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Logi Google Cloud Platform dotyczące aktualizacji pojazdów
Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego UpdateVehicle
. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle
. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Vehicle
.
powłoka
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Powiadomienia Cloud Pub/Sub dotyczące aktualizacji pojazdów
Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub w przypadku aktualizacji istniejącego pojazdu. Aby je otrzymywać, postępuj zgodnie z instrukcjami opisanymi tutaj.
INSTRUKCJA: wyszukiwanie pojazdów
Fleet Engine obsługuje wyszukiwanie pojazdów. Interfejs SearchVehicles
API pozwala znaleźć dostępnych kierowców w pobliżu, którzy najlepiej nadają się do takich zadań jak obsługa przewozu czy prośby o dostawę. Interfejs API SearchVehicles
zwraca ranking kierowców pasujących do atrybutów zadań i atrybutów pojazdów należących do Twojej floty. Więcej informacji znajdziesz w artykule Znajdowanie kierowców w pobliżu.
Przykład
Podczas wyszukiwania dostępnych pojazdów Fleet Engine domyślnie wyklucza pojazdy podczas aktywnych podróży. Usługi dostawcy wspólnych przejazdów lub dostawy muszą być wyraźnie uwzględnione w żądaniach wyszukiwania. Poniższy przykład pokazuje, jak uwzględnić te pojazdy w wynikach wyszukiwania pojazdów pasujących do podróży z centrum handlowego GrandIndonesia East Mall do centrum kongresowego Balai Sidang w Dżakarcie.
powłoka
Najpierw zaktualizuj lokalizację pojazdu, który utworzyliśmy w poprzednich krokach, aby się kwalifikował. W rzeczywistości robi to pakiet Driver SDK działający w pojeździe na urządzeniu z Androidem lub iOS.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Wyszukiwanie powinno zwrócić przynajmniej ten pojazd.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Patrz: providers.vehicles.search.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Zapytanie dotyczące filtrowania pojazdów
SearchVehicles
i ListVehicles
obsługują filtrowanie atrybutów pojazdu za pomocą zapytania filtra. Informacje o składni zapytań filtra znajdziesz na stronie AIP-160.
Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie według atrybutów pojazdów i nie można ich używać w przypadku innych pól. Zapytanie filtra działa jak klauzula AND
z innymi ograniczeniami, np. minimum_capacity
lub vehicle_types
w SearchVehiclesRequest
.
INSTRUKCJA: wyświetlanie listy pojazdów
Usługa SearchVehicles
jest zoptymalizowana pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w rankingu. Służy głównie do znajdowania kierowców w pobliżu, którzy najlepiej się do tego nadają. Czasami jednak chcesz znaleźć wszystkie pojazdy, które spełniają określone kryteria, nawet jeśli konieczne jest stronicowanie wyników. Usługa ListVehicles
została zaprojektowana z myślą o tym zastosowaniu.
Interfejs API ListVehicles
umożliwia znalezienie wszystkich pojazdów, które spełniają określone opcje żądań. Interfejs API ListVehicles
zwraca podzieloną na strony listę pojazdów w projekcie, które spełniają określone wymagania.
Aby filtrować według atrybutów pojazdu, zapoznaj się z sekcją Zapytanie dotyczące filtrowania pojazdów.
Przykład
W tym przykładzie filtruje się pole vehicle_type
i atrybuty za pomocą ciągu znaków filter
.
powłoka
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
Zobacz informacje o providers.vehicles.list.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Podróże i ich cykl życia
Interfejs Trip API i cykl życia są podobne do interfejsu Vehicle API i cyklu życia.
Dostawca wspólnych przejazdów odpowiada za tworzenie podróży za pomocą interfejsów Fleet Engine. Fleet Engine udostępnia zarówno usługę RPC,
TripService
, jak i zasoby REST provider.trips
. Te interfejsy umożliwiają tworzenie elementu Podróże, wysyłanie żądań informacji, funkcje wyszukiwania i aktualizacje.
Element Trip
ma pole stanu, które umożliwia śledzenie postępów w cyklu życia.
Wartości zostaną przeniesione od NEW
do COMPLETE
plus CANCELED
i UNKNOWN_TRIP_STATUS
. Sprawdź trip_status
dla RPC lub TripStatus dla REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Twoja usługa może zaktualizować podróż do: CANCELED
z dowolnego z tych stanów.
Gdy usługa utworzy podróż, wyszukiwarka ustawia jej stan na NEW
. Atrybut vehicle_id
jest opcjonalny. Tak jak w przypadku pojazdów, usługi
usuwają przejazdy automatycznie po 7 dniach bez aktualizacji. Jeśli usługa spróbuje utworzyć podróż z identyfikatorem, który już istnieje, zostanie zwrócony błąd. Podróż jest uznawana za „aktywną”, jeśli ma stan inny niż COMPLETE
lub CANCELED
. To rozróżnienie jest ważne w polu active_trips
w elemencie „Pojazd” i w SearchTripsRequest
.
Usługa vehicle_id
przypisana do podróży może zmienić tylko wtedy, gdy podróż jest aktywna. Możesz to zrobić na przykład wtedy, gdy kierowca anuluje podróż na trasie, a podróż zostanie przypisana do innego pojazdu.
Stan ten jest ważny przy wdrażaniu przebiegu podróży w jedną stronę. Ta pomoc umożliwia Dostawcy przypisanie nowej trasy do Pojazdu, który jest w trakcie aktywnej podróży. Kod do tworzenia „Podróży kolejno po sobie” jest taki sam jak w przypadku pojedynczej podróży i tego samego identyfikatora pojazdu. Fleet Engine dodaje punkt początkowy i cel nowej podróży do punktów na trasie pojazdu. Więcej informacji o kolejnych podróżach znajdziesz w artykule Tworzenie podróży wielopunktowych.
Pozostałe punkty na trasie
Element Trip zawiera powtarzane pole TripWaypoint
(RPC | REST) o nazwie remainingWaypoints
(RPC | REST).
To pole obejmuje wszystkie punkty, które pojazd musi pokonać w ustalonej kolejności, zanim zakończy się podróż w czasie podróży. Oblicza je na podstawie pozostałych punktów na trasie pojazdu.
W przypadkach użycia „Powrot do siebie” i „Podwożenie” ta lista zawiera punkty pośrednie z innych podróży, które zostaną pokonane przed tą podróżą, ale nie uwzględnia punktów pośrednich po tej podróży. Punkt pośredni na liście można rozpoznać po jego TripId
i WaypointType
.
Związek między stanem podróży a pozostałymi punktami na trasie pojazdu
Pozostałe punkty pośrednie pojazdu (RPC | REST) zostaną zaktualizowane, gdy Fleet Engine otrzyma żądanie zmiany stanu podróży. Poprzedni punkt pośredni zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, gdy stan tripStatus
(RPC | REST) zmieni się z innego na ENROUTE_TO_XXX. Oznacza to, że gdy stan podróży zmieni się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru nadal będzie znajdować się na liście pozostałych punktów pośrednich pojazdu, ale gdy stan podróży zmieni się na ENROUTE_TO_INTERMEDIATE_DESTINATION lub ENROUTE_TO_DROPOFF, punkty odbioru zostaną usunięte.
To samo dotyczy ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Przy ARRIVED_AT_INTERMEDIATE_DESTINATION obecny pośredni cel podróży nie zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, dopóki pojazd nie zgłosi, że zbliży się do następnego punktu na trasie.
Po zmianie stanu podróży na COMPLETED
żadne punkty na trasie tej podróży nie będą się wyświetlać na liście pozostałych punktów pośrednich pojazdu.
INSTRUKCJA: tworzenie podróży
Aby można było śledzić każde żądanie podróży i dopasowywać je do pojazdów floty, należy utworzyć element Trip
. Użyj punktu końcowego CreateTrip
z CreateTripRequest
,
aby utworzyć podróż.
Do utworzenia podróży wymagane są te atrybuty:
parent
– ciąg tekstowy zawierający identyfikator dostawcy utworzony podczas tworzenia projektu Google Cloud.trip_id
– ciąg znaków utworzony przez dostawcę wspólnych przejazdów.trip
– kontener z podstawowymi metadanymi opisującymi podróż.trip_type
– wyliczenie określające, czy w podróży mogą być inni pasażerowie z innego miejsca wylotu i z innego miejsca docelowego tym samym pojazdem (SHARED
) czy tylko z jedną osobą (EXCLUSIVE
).pickup_point
– TerminalLocation reprezentujący punkt początkowy podróży. Zobacz dokumentację RPC lub dokumentację REST.
Podczas tworzenia podróży możesz podać number_of_passengers
, dropoff_point
i vehicle_id
. Te pola nie są wymagane, ale jeśli je podasz, zostaną zachowane. Wszystkie pozostałe pola Podróż są ignorowane. Na przykład wszystkie podróże zaczynają się od trip_status
wynoszącego NEW
, nawet jeśli w żądaniu utworzenia przekażesz trip_status
o wartości CANCELED
.
Przykład
W poniższym przykładzie jest tworzona podróż do centrum handlowego Grand Indonesia East Mall. Podróż jest przeznaczona tylko dla 2 pasażerów. provider_id
elementu Trip
musi być taki sam jak identyfikator projektu. W tym przykładzie dostawca wspólnych przejazdów utworzył
projekt Google Cloud project-id. Ten projekt musi mieć konta usługi używane do wywoływania Fleet Engine. Stan podróży to NEW
.
Później, po dopasowaniu usługi do pojazdu, usługa może wywołać metodę UpdateTrip
i zmienić vehicle_id
, gdy podróż zostanie przypisana do pojazdu.
powłoka
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
Więcej informacji znajdziesz w dokumencie providers.trips.create.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Logi Google Cloud Platform dotyczące tworzenia podróży
Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego CreateTrip
. Wpis logu zawiera informacje o wartościach w żądaniu CreateTrip
. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Trip
.
WSKAZÓWKA: aktualizowanie podróży
Element Trip zawiera pola, które umożliwiają śledzenie podróży przez usługę oraz raportowanie postępów podróży przez pakiet Driver SDK i pakiet SDK dla klientów indywidualnych. Aby zaktualizować właściwości, użyj komunikatu UpdateTripRequest
. Spowoduje to zaktualizowanie pól Podróży zgodnie z wartością field_mask
żądania.
Zobacz UpdateTripRequest.
Dostawca wspólnych przejazdów odpowiada za aktualizację tych atrybutów:
- Stan podróży.
- Identyfikator pojazdu. W momencie utworzenia lub po dopasowaniu pojazdu do trasy.
- Zmiany dotyczące odbioru, odjazdu lub punktów pośrednich.
Fleet Engine automatycznie aktualizuje te pola, gdy używasz funkcji udostępniania trasy za pomocą pakietu Driver SDK lub pakietu SDK dla klientów indywidualnych:
- Trasy
- Szacowany czas dotarcia
- Pozostały dystans
- Lokalizacja pojazdu
- Pozostałe punkty pośrednie
Sprawdź Trip
w RPC lub Resource.Trip
w REST.
Logi Google Cloud Platform dotyczące aktualizacji podróży
Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego UpdateTrip
. Wpis logu zawiera informacje o wartościach w żądaniu UpdateTrip
. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Trip
.
INSTRUKCJA: wyszukiwanie wycieczek
Fleet Engine obsługuje wyszukiwanie podróży. Jak wspomnieliśmy, podróż jest automatycznie usuwana po 7 dniach, więc SearchTrips
nie udostępnia pełnej historii wszystkich Podróży.
SearchTrips
to elastyczny interfejs API, ale poniższa lista uwzględnia 2 przypadki użycia.
Określanie aktywnych podróży pojazdu – Dostawca może określić obecnie aktywne podróże pojazdu. W
SearchTripsRequest
wartośćvehicle_id
jest ustawiona na rozważany pojazd, aactive_trips_only
powinna mieć wartośćtrue
.Uzgadnianie stanu dostawcy i floty floty – dostawca może użyć parametru
SearchTrips
, aby sprawdzić, czy stan ich podróży i Fleet Engine są zgodne. Jest to szczególnie ważne w przypadku aplikacji TripStatus. Jeśli stan podróży przypisanej do pojazdu nie jest prawidłowo ustawiony naCOMPLETE
lubCANCELED
, pojazd nie jest uwzględniany przezSearchVehicles
.
Aby użyć SearchTrips
w ten sposób, pozostaw pole vehicle_id
puste, ustaw active_trips_only
na true
, a minimum_staleness
ustaw czas dłuższy niż większość czasu trwania podróży.
Możesz na przykład wybrać 1 godzinę. Wyniki obejmują Podróże, które nie zostały
UKOŃCZONE ani ANULOWANE i nie zostały zaktualizowane od ponad godziny. Dostawca powinien sprawdzić te Podróże, aby upewnić się, że ich stan we Fleet Engine jest odpowiednio zaktualizowany.
Rozwiązywanie problemów
W przypadku błędu DEADLINE_EXCEEDED
stan Fleet Engine jest nieznany. Dostawca powinien ponownie wywołać metodę CreateTrip
, która zwraca kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednie żądanie zostało zrealizowane przed DEADLINE_EXCEEDED
. Więcej informacji o postępowaniu w przypadku błędów podróży znajdziesz w przewodnikach dotyczących interfejsu Consumer API: Android lub iOS.
Obsługa podwożenia w podróży
Możesz przypisać kilka przejazdów typu SHARED
do pojazdu, który obsługuje usługę TripType.SHARED
.
Musisz określić kolejność wszystkich nieprzebytych punktów na trasie wszystkich podróży przypisanych do pojazdu w ramach tego wspólnego przejazdu przez Trip.vehicle_waypoints
, gdy przypisujesz adres vehicle_id
do wspólnej podróży (w żądaniu CreateTrip
lub UpdateTrip
).
Sprawdź vehicle_waypoints
dla RPC lub vehicleWaypoints
dla REST.
Obsługa wielu miejsc docelowych
Określ średniozaawansowane miejsce docelowe
Pole intermediateDestinations
i pole intermediateDestinationIndex
w Trip (RPC | REST) są łączone, aby wskazać miejsce docelowe.
Zaktualizuj pośrednie miejsce docelowe
Miejsca docelowe pośrednie możesz zaktualizować w: UpdateTrip
. Podczas aktualizowania pośrednich miejsc docelowych musisz podać pełną listę pośrednich miejsc docelowych łącznie z tymi, które zostały już odwiedzone, a nie tylko te nowo dodane lub zmienione.
Gdy intermediateDestinationIndex
wskazuje indeks po pozycji nowo dodanego/zmodyfikowanego pośredniego miejsca docelowego, nowe/zaktualizowane miejsce docelowe nie zostanie dodane do: waypoints
pojazdu ani remainingWaypoints
podróży.
Powodem jest to, że wszystkie miejsca docelowe pośrednie przed intermediateDestinationIndex
są traktowane jako już odwiedzone.
Zmiany stanu podróży
Pole intermediateDestinationsVersion
w (RPC | REST) jest wymagane w żądaniu aktualizacji stanu podróży wysyłanym do Fleet Engine, aby wskazać, że pośrednie miejsce docelowe zostało już przekazane. Docelowe pośrednie miejsce docelowe określa się w polu intermediateDestinationIndex
.
Gdy tripStatus
(RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, liczba z zakresu [0..N-1] wskazuje pośrednie miejsce docelowe, przez które pojazd będzie następny.
Jeśli tripStatus
to ARRIVED_AT_INTERMEDIATE_DESTINATION, liczba z zakresu od [0..N-1] wskazuje pośrednie miejsce docelowe, na którym znajduje się pojazd.
Przykład
Poniższy przykładowy kod pokazuje, jak zaktualizować stan podróży, aby wrócić do pierwszego pośredniego miejsca docelowego, przy założeniu, że została utworzona podróż obejmująca wiele miejsc docelowych i została ona zakończona.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
INSTRUKCJA: subskrybowanie powiadomień z interfejsu Fleet Engine API
Fleet Engine API używa Google Cloud Pub/Sub do publikowania powiadomień na temat utworzonego przez projekt Google Cloud dla klientów indywidualnych. Usługa Pub/Sub nie jest domyślnie włączona dla Fleet Engine w Twoim projekcie Google Cloud. Aby włączyć Pub/Sub, prześlij zgłoszenie do zespołu pomocy lub skontaktuj się z inżynierem ds. obsługi klienta.
Aby utworzyć temat w projekcie Cloud, wykonaj te instrukcje. Identyfikator tematu musi mieć wartość „fleet_engine_notifications”.
Temat musi być utworzony w tym samym projekcie Cloud, który wywołuje interfejsy Fleet Engine API.
Po utworzeniu tematu musisz przyznać interfejsowi Fleet Engine API uprawnienia do publikowania w tym temacie. Aby to zrobić, kliknij utworzony przed chwilą temat
i dodaj nowe uprawnienie. Aby otworzyć edytor uprawnień, konieczne może być kliknięcie POKAŻ PANEL INFORMACYJNY.
Podmiotem zabezpieczeń powinien być geo-fleet-engine@system.gserviceaccount.com
, a rola powinna mieć wartość Pub/Sub publisher
.
Aby skonfigurować w projekcie Cloud subskrypcję powiadomień, postępuj zgodnie z tymi instrukcjami
Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych formatach danych: protobuf
i json
. Format danych każdego powiadomienia jest określony w atrybutach PubsubMessage kluczem jako data_format
, a wartością jest protobuf
lub json
.
Schemat powiadomień:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}