Interfejs Fleet Engine – On-Demand Rides and Deliveries API umożliwia zarządzanie podróżami i stanem pojazdów w aplikacjach Podróże i Postępy zamówień. Obsługuje transakcje między pakietem SDK sterownika, pakietem SDK dla konsumentów i usługą backendu, które mogą komunikować się z Fleet Engine za pomocą wywołań gRPC lub REST.
Wymagania wstępne
Na potrzeby programowania pamiętaj, aby zainstalować pakiet SDK Cloud (gcloud) i uwierzytelnić się w projekcie.
powłoka
gcloud auth login
Powinien pojawić 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 Fleet Engine API dotyczące przejazdów i dostaw na żądanie są prawidłowo skonfigurowane.
powłoka
gcloud --project=project-id services enable fleetengine.googleapis.com
Jeśli to polecenie powoduje błąd, skontaktuj się z administratorem projektu i przedstawicielem zespołu pomocy Google, aby uzyskać dostęp.
Logowanie
Fleet Engine może zapisywać komunikaty dotyczące odbieranych wywołań interfejsu API w logach platformy Google Cloud. Informacje o tym, jak odczytywać i analizować logi, znajdziesz w dokumentacji Cloud Logging.
W projektach utworzonych przed 10 lutego 2022 r. logowanie może nie być domyślnie włączone. Więcej informacji znajdziesz w dokumentacji dotyczącej logowania.
Biblioteki klienta
Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te biblioteki ułatwiają pracę programistom w porównaniu z nieprzetworzonym REST lub gRPC. Instrukcje uzyskiwania bibliotek klienta dla aplikacji serwera znajdziesz w artykule Biblioteki klienta.
W przykładach w języku Java w tej dokumentacji założono, że znasz gRPC.
Uwierzytelnianie i autoryzacja
Możliwości związane z podróżą i postępem 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 przy użyciu kont usługi utworzonych w Cloud Console.
Konfigurowanie projektu w chmurze
Aby skonfigurować projekt w chmurze, najpierw utwórz projekt, a potem utwórz konta usługi.
Aby utworzyć projekt Google Cloud:
- Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
- W 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żą one 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żesz utworzyć wiele kont usługi o minimalnym zestawie wymaganych ról.
Postęp podróży i zamówienia ma następujące role:
Rola | Opis |
---|---|
Użytkownik pakietu SDK konsumenta Fleet Engine roles/fleetengine.consumerSdkUser |
Daje uprawnienie do wyszukiwania pojazdów oraz pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi o tej roli są zwykle używane z urządzeń mobilnych w aplikacji do wspólnych przejazdów lub dostawy. |
Użytkownik pakietu SDK Fleet Engine Driver SDK roles/fleetengine.driverSdkUser |
Daje uprawnienie do aktualizowania lokalizacji pojazdów i tras oraz do pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi o tej roli są zwykle używane na urządzeniach mobilnych w aplikacji do wspólnych przejazdów lub dostawcy. |
Superużytkownik usługi Fleet Engine roles/fleetengine.serviceSuperUser |
Przyznaje uprawnienia wszystkim interfejsom API pojazdów i podróży. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z serwerów backendu. |
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
Na tych standardowych rolach opierają się pakiety SDK sterowników i konsumenta.
Możesz też utworzyć role niestandardowe, które pozwalają łączyć ze sobą dowolny zestaw uprawnień. Pakiety SDK sterowników i konsumenta wyświetlają komunikaty o błędach, gdy brakuje wymaganego uprawnienia. Dlatego zdecydowanie zalecamy, aby nie korzystać ze standardowego zestawu ról, ale nie z nich niestandardowych.
Jeśli chcesz tworzyć tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi umożliwia im tworzenie tokenów 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 API Fleet Engine. Nowa biblioteka uwierzytelniania Fleet Engine dostępna na GitHubie upraszcza tworzenie tokenów JWT Fleet Engine i bezpieczne ich podpisy.
Biblioteka zapewnia te korzyści:
- Upraszcza proces tworzenia tokenów Fleet Engine.
- Udostępnia mechanizmy podpisywania tokenów inne niż pliki danych logowania (np. podszywanie się pod konto usługi).
- Dołącza podpisane tokeny do żądań wychodzących, które pochodzą z odcinka gRPC lub klienta GAPIC.
Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji
Jeśli nie korzystasz z biblioteki uwierzytelniania Fleet Engine, tokeny internetowe JSON (JWT) musisz utworzyć bezpośrednio w bazie kodu. Musisz więc dogłębnie znać tokeny JWT i ich związek z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.
Tokeny internetowe JSON (JWT) w Fleet Engine zapewniają krótkotrwałe uwierzytelnianie i zapewniają, że urządzenia mogą modyfikować tylko pojazdy, podróże lub zadania, do których są autoryzowane. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera takie informacje jak klucz prywatny do użycia (uzyskany z kont usługi) i algorytm szyfrowania. Sekcja roszczenia zawiera takie informacje jak czas utworzenia tokena, czas życia tokenów, usługi, do których zgłoszono prawa dostępu, i inne informacje o autoryzacji umożliwiające określenie zakresu dostępu, np. identyfikator pojazdu.
Sekcja nagłówka JWT zawiera te pola:
Pole | Opis |
---|---|
alg | Algorytm, którego chcesz użyć. „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 z odpowiednim poziomem uprawnień. |
Sekcja deklaracji JWT zawiera te pola:
Pole | Opis |
---|---|
iss | Adres e-mail Twojego konta usługi. |
zast. | Adres e-mail Twojego konta usługi. |
jst | Usługa SERVICE_NAME Twojego konta usługi, w tym przypadku https://fleetengine.googleapis.com/ |
IAT | Sygnatura czasowa utworzenia tokena podana w sekundach, które upłynęły od 00:00:00 czasu UTC 1 stycznia 1970 r. Odczekaj 10 minut, aby się zniekształcić. 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 1 stycznia 1970 r. o godz. 00:00:00 czasu UTC. Żądanie nie powiedzie się, jeśli sygnatura czasowa przypada za więcej niż godzinę. |
autoryzacja | W zależności od przypadku użycia może zawierać parametr „vehicleid” lub „tripid”. |
Tworzenie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz w artykule Autoryzacja konta usługi bez OAuth. Potem 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 dodatkowe deklarację w sekcji autoryzacji, gdzie klucz vehicleid
lub tripid
jest ustawiony na wartość identyfikatora pojazdu lub identyfikatora podróży, w przypadku którego wykonywane jest wywołanie.
Pakiet SDK kierowcy zawsze używa deklaracji vehicleid
, niezależnie od tego, czy odbywa się w podróży, czy w pojeździe. Backend Fleet Engine zapewnia, że pojazd jest powiązany z żądaną podróżą przed wprowadzeniem modyfikacji.
Pakiet SDK dla klientów indywidualnych zawsze używa deklaracji tripid
.
Dostawca wspólnych przejazdów lub dostawy powinien użyć atrybutu vehicleid
lub tripid
ze znakiem „*”, aby dopasować wszystkie pojazdy i Podróże. Pamiętaj, że token JWT może zawierać oba tokeny, nawet jeśli nie jest to wymagane. Upraszcza to implementację podpisywania tokenów.
Przypadki użycia JWT
Poniżej znajdziesz przykładowy token dla serwera 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 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 znajduje się 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
pliku JSON konta usługi. - W polach
iss
isub
podaj adres e-mail konta usługi. Tę wartość znajdziesz w poluclient_email
pliku JSON konta usługi. - W polu
aud
podaj https://SERVICE_NAME/. - W polu
iat
użyj sygnatury czasowej utworzenia tokena określonej jako sekundy, które upłynęły od 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut, aby się zniekształcić. Jeśli sygnatura czasowa jest w zbyt odległej przeszłości lub przypada w przyszłości, serwer może zgłosić błąd. - W polu
exp
użyj sygnatury czasowej wygaśnięcia tokena określonej jako sekundy od godziny 00:00:00 czasu UTC, 1 stycznia 1970 roku. Maksymalna dozwolona wartość toiat
+ 3600.
Podczas podpisywania tokena JWT, który ma zostać przekazany na urządzenie mobilne, użyj konta usługi do roli sterownika lub pakietu SDK klienta. W przeciwnym razie urządzenie mobilne będzie miało możliwość zmiany stanu.
Podobnie, jeśli podpisujesz token JWT, który ma być używany na potrzeby wywołań uprzywilejowanych, użyj konta usługi z rolą superużytkownika. W przeciwnym razie operacja się nie powiedzie.
Tworzenie tokena JWT na potrzeby testowania
Podczas testowania może być pomocne generowanie tokenów z terminala.
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 epoce. Można go wyszukać, uruchamiając w terminalu date +%s
. Właściwość exp
to czas wygaśnięcia wyrażony w sekundach po epoce, który można obliczyć, dodając wartość 3600 do wartości iat
. Czas wygaśnięcia nie może być dłuższy niż 1 godzina 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 superużytkownika:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
Podpisany token JWT zakodowany w Base64 powinien być teraz przechowywany w pliku signed_token.jwt
. Token jest ważny przez następną godzinę.
Możesz teraz przetestować token, uruchamiając polecenie curl
w punkcie końcowym Wyświetlenie pojazdów 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 element reprezentujący parę kierowcy-pojazd. Obecnie nie można osobno śledzić kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawy tworzy pojazd za pomocą identyfikatora dostawcy (który musi być taki sam jak identyfikator projektu Google Cloud zawierającego konto usługi używane do wywoływania interfejsów Fleet Engine API) oraz identyfikatora pojazdu należącego do dostawcy usług wspólnych lub dostawy.
Pojazd, który w ciągu 7 dni nie został zaktualizowany w aplikacji UpdateVehicle
, zostanie automatycznie usunięty. Wystąpił błąd podczas wywoływania funkcji CreateVehicle
z użyciem istniejącej pary identyfikator dostawcy/identyfikator pojazdu. W przypadku pojazdów, które nie są często aktualizowane, można załatwić takie sprawy na 2 sposoby: często wywołując CreateVehicle
oczekiwaną parę identyfikatora dostawcy/identyfikatora pojazdu i odrzucając błąd, jeśli pojazd już istnieje, lub wywoływanie CreateVehicle
po wystąpieniuUpdateVehicle
zwrócenia błędu NOT_FOUND
.
Aktualizacje lokalizacji pojazdu
Aby uzyskać najlepszą wydajność Fleet Engine, zapewnij jej strumień aktualizacji lokalizacji pojazdów. Aktualizacje możesz przesłać na jeden z tych sposobów:
- Użyj pakietu SDK sterownika – Android, iOS – najprostsza opcja.
- Użyj kodu niestandardowego, który jest przydatny, gdy lokalizacje są przekazywane przez backend lub używasz 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 SearchVehicles
i ListVehicles
.
W przypadku wszystkich tras dla pojazdów używana jest odpowiednia wartość 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 pole powtarzane VehicleAttribute
. Te atrybuty nie są interpretowane przez Fleet Engine. Interfejs SearchVehicles
API zawiera pole, które wymaga, aby dopasowane Vehicles
musi 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 drodze dla pojazdów
Element Vehicle zawiera pole powtarzane TripWaypoint
(RPC | REST) o nazwie waypoints
(RPC | REST).
To pole zawiera pozostałe punkty na trasie w kolejności, w jakiej do nich dotrze. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je wraz ze zmianą stanu podróży.
Takie punkty na trasie można rozpoznać po polach TripId
i WaypointType
.
Rozszerzanie możliwości dopasowania pojazdu
Zwykle za dopasowywanie żądań przejazdu do pojazdów odpowiada firma świadcząca usługi w zakresie przejazdów lub dostawy. Usługa może korzystać z atrybutów pojazdu, aby uwzględnić pojazd w większej liczbie wyszukiwań. Na przykład usługodawca może wdrożyć zestaw atrybutów odpowiadających poziomom bonusów lub możliwości oferowanych przez pojazd. Na przykład 3 poziomy mogą być zbiorem atrybutów z wartościami logicznymi: is_bronze_level
, is_silver_level
i is_gold_level
. Pojazd może spełniać wszystkie 3 warunki. Gdy Fleet Engine otrzyma prośbę o podróż, która wymaga srebrnych możliwości, wyszukiwanie uwzględnia ten pojazd.
Ten sposób korzystania z atrybutów obejmuje pojazdy o różnych możliwościach.
Atrybuty pojazdu można aktualizować na 2 sposoby. Jeden z nich to UpdateVehicle
API. Gdy używasz tego interfejsu API, cały zestaw atrybutów pojazdu jest ustawiony na wartość. Nie można aktualizować tylko jednego atrybutu.
Druga metoda to interfejs API UpdateVehicleAttributes
. Ta metoda wymaga tylko aktualizacji atrybutów. Atrybuty uwzględnione w żądaniu zostaną ustawione na nową wartość lub dodane. Nieokreślone atrybuty nie zostaną zmienione.
PORADNIK: Utwórz pojazd
Dla każdego pojazdu, który ma być śledzony we flocie, należy utworzyć element Vehicle
.
Użyj punktu końcowego CreateVehicle
z CreateVehicleRequest
do utworzenia pojazdu.
Element provider_id
obiektu Vehicle
musi być identyfikatorem projektu (np. mój projekt na żądanie) projektu Google Cloud zawierającego konta usługi, które będą używane do wywołania Fleet Engine. Pamiętaj, że chociaż wiele kont usługi może korzystać z Fleet Engine dla tego samego dostawcy usług udostępniania lub przejazdów, Fleet Engine nie obsługuje obecnie kont usługi z wielu projektów Google Cloud, które mają dostęp do tego samego zasobu Vehicles
.
Element Vehicle
można utworzyć w stanie OFFLINE
lub ONLINE
. Jeśli zostanie utworzony ONLINE
, może zostać natychmiast zwrócony w odpowiedzi na SearchVehicles
zapytań.
Wywołanie CreateVehicle
może zawierać początkowy element last_location
.
Chociaż jest to dozwolone, Vehicle
nie należy tworzyć 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 utworzona encja 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
Zobacz dokumentację dotyczącą 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 pojazdów
Po otrzymaniu wywołania punktu końcowego CreateVehicle
interfejs Fleet Engine API zapisuje w logach platformy Google Cloud wpis logu. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym 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 pojazdów
Po utworzeniu nowego pojazdu interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcjami opisanymi tutaj.
Podpowiedź: zaktualizuj lokalizację pojazdu
Jeśli nie zaktualizujesz lokalizacji pojazdu za pomocą pakietu Driver SDK, możesz wykonać bezpośrednie wywołanie do Fleet Engine i podać lokalizację 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. Te aktualizacje wymagają tylko uprawnień użytkownika 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
Zobacz dokumentację 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.
Podpowiedź: zaktualizuj inne pola dotyczące pojazdów
Aktualizacje innych atrybutów stanu pojazdu występują rzadziej niż aktualizacje pozycji. Aktualizacje atrybutów innych niż last_location
wymagają uprawnień superużytkownika Fleet Engine.
UpdateVehicleRequest
zawiera element update_mask
wskazujący, które pola mają zostać zaktualizowane. Sposób działania pola jest taki sam jak w dokumentacji Protobuf dla masek pól.
Jak wspomnieliśmy w sekcji Atrybuty pojazdu, zaktualizowanie pola attributes
wymaga zapisania wszystkich atrybutów, które zostaną zachowane. Nie można po prostu zaktualizować wartości jednej pary klucz-wartość w wywołaniu UpdateVehicle
. Do aktualizowania wartości określonych atrybutów można użyć interfejsu API UpdateVehicleAttributes
.
Przykład
Ten przykład włącza funkcję 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
Zobacz dokumentację 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 na potrzeby aktualizacji pojazdu
Po otrzymaniu wywołania punktu końcowego UpdateVehicle
interfejs Fleet Engine API zapisuje w logach platformy Google Cloud wpis logu. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym 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 o aktualizacjach pojazdu
Gdy istniejący pojazd zostanie zaktualizowany, interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcjami opisanymi tutaj.
PORADNIK: Wyszukiwanie pojazdów
Fleet Engine obsługuje wyszukiwanie pojazdów. Interfejs SearchVehicles
API pozwala znajdować w pobliżu kierowców, którzy najlepiej sprawdzą się w takich zadaniach jak obsługa przejazdów czy zamówienia dostawy. Interfejs SearchVehicles
API zwraca ranking kierowców pasujących do atrybutów zadań i atrybutów pojazdów w Twojej flocie. 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 aktywne. Usługi dostawców usług wspólnych przejazdów lub dostawy muszą być wyraźnie uwzględnione w żądaniach wyszukiwania. Z przykładu poniżej dowiesz się, jak uwzględnić te pojazdy w wyszukiwaniu 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 świecie rzeczywistym robi to w pojeździe pakietu SDK Driver SDK 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
Po przeprowadzeniu wyszukiwania powinien być co najmniej 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
Zobacz dokumentację 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 o filtr. Składnię zapytań filtra znajdziesz w AIP-160.
Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie według atrybutów pojazdu i nie można ich używać w innych polach. Zapytanie filtra działa jak klauzula AND
z innymi ograniczeniami, takimi jak minimum_capacity
lub vehicle_types
w SearchVehiclesRequest
.
PORADNIK: Wyświetlanie listy pojazdów
Narzędzie SearchVehicles
zostało zoptymalizowane pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w rankingu i głównie do znajdowania kierowców w pobliżu najlepiej pasujących do konkretnego zadania. Czasami jednak chcesz znaleźć wszystkie pojazdy, które spełniają określone kryteria, nawet jeśli konieczne jest stronicowanie wyników. Typ ListVehicles
został opracowany z myślą o tym przypadku.
Interfejs ListVehicles
API pozwala znaleźć wszystkie pojazdy, które spełniają określone opcje żądania. Interfejs ListVehicles
API zwraca w projekcie podzieloną na strony listę pojazdów, które spełniają niektóre wymagania.
Aby filtrować według atrybutów pojazdu, zapoznaj się z artykułem Zapytanie dotyczące filtrowania pojazdów.
Przykład
W tym przykładzie filtrujemy pola vehicle_type
i atrybuty przy użyciu 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 dokumentację 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
. Umożliwiają one tworzenie obiektów Trip, wysyłanie żądań informacji, wyszukiwanie oraz aktualizowanie treści.
Element Trip
ma pole stanu, które pozwala śledzić jego postęp w całym cyklu życia.
Wartości są przenoszone z NEW
do COMPLETE
plus CANCELED
i UNKNOWN_TRIP_STATUS
. Zapoznaj się z informacjami o trip_status
RPC
i Stanie Trip 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 tworzy podróż, wyszukiwarka ustawia jej stan na NEW
. Wartość vehicle_id
jest opcjonalna. Tak jak w przypadku pojazdów, usługi usuwają podróże automatycznie
po 7 dniach bez aktualizacji. Jeśli Twoja usługa spróbuje utworzyć podróż o identyfikatorze, który już istnieje, zostanie zwrócony błąd. Podróż jest uznawana za „aktywną”, jeśli ma inny stan niż COMPLETE
lub CANCELED
. To rozróżnienie jest ważne w polu active_trips
w elemencie Pojazd i w polu SearchTripsRequest
.
Usługa może zmienić vehicle_id
przypisany do podróży tylko wtedy, gdy stan to NEW
lub CANCELED
. Jeśli Kierowca anuluje podróż, gdy jest w drodze, stan Podróży musi być ustawiony na NEW
lub CANCELED
, zanim vehicle_id
zostanie zmieniony lub usunięty.
Stan jest ważny przy wdrażaniu dodatkowej obsługi podróży. Ta obsługa umożliwia Dostawcy przypisanie nowej podróży do Pojazdu, gdy jest on w aktywnej podróży. Kod do utworzenia podróży po kolei jest taki sam jak w przypadku pojedynczej podróży i korzysta z tego samego identyfikatora pojazdu. Fleet Engine dodaje miejsce początkowe i cel nowej podróży do punktów na trasie pojazdu. Więcej informacji o podróży po kolei znajdziesz w artykule Tworzenie podróży obejmujących wiele punktów pośrednich.
Pozostałe punkty na trasie
Element Trip zawiera pole powtarzane TripWaypoint
(RPC | REST) o nazwie remainingWaypoints
(RPC | REST).
To pole zawiera wszystkie punkty pośrednie, którymi pojazd musi podróżować w kolejności, zanim będzie ostatni punkt docelowy w tej podróży. Oblicza je na podstawie
pozostałych punktów na trasie pojazdu.
W przypadku korzystania z podróży wstecz i podwożenia ta lista zawiera punkty na trasie z innych podróży, które zostaną przebyte przed tą podróżą, ale nie zawiera punktów pośrednich po niej. Punkt pośredni na liście można rozpoznać po elementach TripId
i WaypointType
.
Zależność między stanem podróży a pozostałymi punktami na trasie pojazdu
Pozostałe punkty drogi 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 status podróży zmieni się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru będzie nadal widoczny na liście pozostałych punktów pośrednich pojazdu, ale gdy status podróży zmieni się na ENROUTE_TO_INTERMEDIATE_DESTINATION lub ENROUTE_TO_DROPOFF, punkt odbioru zostanie usunięty.
Tak samo jest w przypadku ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Gdy ARRIVED_AT_INTERMEDIATE_DESTINATION bieżący pośredni punkt docelowy nie zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, dopóki pojazd nie zgłosi, że prowadzi do następnego punktu pośredniego.
Gdy stan podróży zostanie zmieniony na COMPLETED
, żadne punkty pośrednie z tej podróży nie będą widoczne na liście pozostałych punktów pośrednich pojazdu.
PORADNIK: Utwórz podróż
Aby każde żądanie podróży było śledzone i dopasowywane do pojazdów we flocie, 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 znaków zawierający identyfikator dostawcy utworzony podczas tworzenia projektu Google Cloud.trip_id
– ciąg tekstowy utworzony przez dostawcę wspólnych przejazdów.trip
– kontener z podstawowymi metadanymi opisującymi podróż.trip_type
– liczba wskazująca, czy w podróży mogą uczestniczyć tylko pasażerowie z innego miejsca wylotu i celu podróży w tym samym pojeździe (SHARED
) lub tylko w ramach tej podróży (EXCLUSIVE
).pickup_point
– TerminalLocation wskazujący punkt początkowy podróży. Więcej informacji znajdziesz w dokumentacji RPC lub dokumentacji REST.
Podczas tworzenia podróży możesz podać te informacje: number_of_passengers
, dropoff_point
i vehicle_id
. Chociaż te pola nie są wymagane, jeśli je podasz, zostaną zachowane. Pozostałe pola Podróże są ignorowane. Na przykład wszystkie podróże zaczynają się od trip_status
o wartości NEW
nawet wtedy, gdy w żądaniu utworzenia prześlesz trip_status
o wartości CANCELED
.
Przykład
Poniższy przykład tworzy wycieczkę do Grand Indonesia East Mall. Podróż jest przeznaczona
dla 2 pasażerów i jest przeznaczona tylko dla 2 pasażerów. Wartość provider_id
elementu Trip
musi być taka sama 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, gdy usługa dopasuje podróż do pojazdu, usługa może wywołać 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
Zobacz dokumentację dotyczącą 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 na potrzeby tworzenia podróży
Po otrzymaniu wywołania punktu końcowego CreateTrip
interfejs Fleet Engine API zapisuje wpis logu przy użyciu logów platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu CreateTrip
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym elemencie Trip
.
Podpowiedź: zaktualizuj informacje o podróży
Element Trip zawiera pola umożliwiające śledzenie przez usługę oraz raportowanie postępów w podróży przez pakiet SDK sterownika i pakiet SDK dla konsumentów. Aby zaktualizować właściwości, użyj komunikatu UpdateTripRequest
. Spowoduje to zaktualizowanie pól Podróż zgodnie z field_mask
żądania.
Zobacz UpdateTripRequest.
Dostawca wspólnych przejazdów odpowiada za aktualizowanie tych atrybutów:
- Stan podróży.
- Identyfikator pojazdu. W momencie tworzenia pojazdu lub po dopasowaniu pojazdu do podróży.
- Zmiany dotyczące punktu odbioru, miejsca docelowego lub punktów pośrednich.
Podczas korzystania z funkcji udostępniania trasy za pomocą pakietu Driver SDK lub Consumer SDK Fleet Engine automatycznie aktualizuje te pola:
- Trasy
- Szacowany czas dotarcia
- Pozostała odległość
- Lokalizacja pojazdu
- Pozostałe punkty na trasie
Skorzystaj z instrukcji Trip
w RPC lub Resource.Trip
w REST.
Logi Google Cloud Platform na potrzeby aktualizacji podróży
Po otrzymaniu wywołania punktu końcowego UpdateTrip
interfejs Fleet Engine API zapisuje wpis logu przy użyciu logów platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu UpdateTrip
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym Trip
.
PORADNIK: Wyszukiwanie podróży
Fleet Engine obsługuje wyszukiwanie podróży. Jak już 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 na poniższej liście uwzględniono 2 przypadki użycia.
Określanie aktywnych podróży pojazdu – Dostawca może określić aktywne podróże pojazdu. W
SearchTripsRequest
właściwośćvehicle_id
jest ustawiona na rozważany pojazd, aactive_trips_only
– natrue
.Uzgadnianie dostawcy i stanu Fleet Engine – dostawca może użyć
SearchTrips
, aby upewnić się, że stan podróży jest taki sam jak stan Fleet Engine. Jest to szczególnie ważne w przypadku obiektu TripStatus. Jeśli stan podróży przypisany do Pojazdu nie jest prawidłowo ustawiony naCOMPLETE
lubCANCELED
,SearchVehicles
nie uwzględnia tego pojazdu.
Aby użyć elementu SearchTrips
w ten sposób, pozostaw pole vehicle_id
puste, ustaw active_trips_only
na true
i ustaw wartość minimum_staleness
na czas dłuższy niż większość czasu trwania podróży.
Możesz użyć np. godziny. Wyniki obejmują podróże, które nie są UKOŃCZONE ani ANULOWANE i które nie zostały zaktualizowane w ciągu godziny. Dostawca powinien sprawdzić te podróże, aby upewnić się, że ich stan we Fleet Engine jest prawidłowo zaktualizowany.
Rozwiązywanie problemów
W przypadku błędu DEADLINE_EXCEEDED
stan Fleet Engine jest nieznany. Dostawca powinien ponownie wywołać funkcję CreateTrip
, która zwraca kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednia prośba została zrealizowana przed DEADLINE_EXCEEDED
. Więcej informacji o obsłudze błędów w podróżach znajdziesz w przewodnikach po interfejsie Consumer API na Androidzie i iOS.
Obsługa przejazdów Carpool
Do pojazdu obsługującego TripType.SHARED
możesz przypisać kilka podróży typu SHARED
.
Musisz określić kolejność wszystkich nieprzekazanych punktów pośrednich we wszystkich podróżach przypisanych do pojazdu w ramach tej wspólnej przejazdu za pomocą Trip.vehicle_waypoints
, gdy przypisujesz element vehicle_id
do podróży współdzielonej (w żądaniu CreateTrip
lub UpdateTrip
).
Zapoznaj się z informacjami na temat vehicle_waypoints
dla RPC i vehicleWaypoints
dla REST.
Obsługa wielu miejsc docelowych
Wskaż pośrednie miejsce docelowe
Pola intermediateDestinations
i intermediateDestinationIndex
w podróży (RPC | REST) zostaną połączone, aby wskazać miejsce docelowe.
Zaktualizuj pośrednie miejsce docelowe
Miejsca docelowe pośrednich możesz zaktualizować na stronie UpdateTrip
. Podczas aktualizowania miejsc docelowych pośrednich musisz podać pełną listę miejsc docelowych pośrednich, łącznie z odwiedzonymi miejscami docelowymi, a nie tylko tymi, które zostały niedawno dodane lub zmienione.
Gdy intermediateDestinationIndex
wskazuje indeks po pozycji nowo dodanego/zmodyfikowanego pośredniego miejsca docelowego, nowe/zaktualizowane pośrednie miejsce docelowe nie zostanie dodane do miejsca waypoints
pojazdu ani do kolumny remainingWaypoints
podróży.
Przyczyną jest to, że wszystkie miejsca docelowe pośrednie przed intermediateDestinationIndex
są traktowane jak 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 miejsce docelowe pośrednie zakończyło się powodzeniem. Docelowy pośredni punkt docelowy jest określony w polu intermediateDestinationIndex
.
Gdy tripStatus
(RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, liczba z zakresu od [0..N-1] wskazuje, przez który pośredni punkt docelowy pojazd przejedziesz pojazdem.
Gdy tripStatus
to ARRIVED_AT_INTERMEDIATE_DESTINATION, liczba z zakresu
[0..N-1] wskazuje, gdzie znajduje się pojazd.
Przykład
Poniższy przykładowy kod pokazuje, jak zaktualizować stan podróży, aby dotrzeć do pierwszego miejsca docelowego pośredniego, przy założeniu, że masz utworzoną podróż obejmującą wiele miejsc docelowych i minęła już jej punkt odbioru.
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;
}
PORADNIK: subskrybowanie powiadomień z interfejsu Fleet Engine API
Fleet Engine API wykorzystuje Google Cloud Pub/Sub do publikowania powiadomień na temat utworzony przez konsumenta Google Cloud Project. 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 zostać 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 to Pub/Sub publisher
.
Jeśli chcesz skonfigurować projekt Cloud pod kątem subskrypcji powiadomień, wykonaj te instrukcje
Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych formatach danych: protobuf
i json
. Format danych każdego powiadomienia jest oznaczony w atrybutach PubsubMessage kluczem data_format
i wartością 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"
}
}
}