Interfejs Fleet Engine On-demand Rides and Deliveries API umożliwia zarządzanie podróżami i stanem pojazdów w aplikacjach związanych z podróżami i postępami składania zamówień. Obsługuje transakcje między pakietem SDK sterownika, pakietem SDK dla konsumentów a usługą backendu, które mogą komunikować się z Fleet Engine przez wywołania gRPC lub REST.
Wymagania wstępne
Pamiętaj, aby zainstalować pakiet SDK Cloud (gcloud) i uwierzytelnić się w projekcie.
powłoka
gcloud auth login
Powinien wyświetlić się taki komunikat o powodzeniu:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Sprawdź, czy interfejsy Fleet Engine API do obsługi 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 logu o odbieranych wywołaniach interfejsu API w logach platformy Google Cloud. Omówienie sposobu odczytywania i analizowania logów 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. Ułatwiają one programistom pracę w przypadku nieprzetworzonego kodu REST lub gRPC. Instrukcje na temat uzyskiwania bibliotek klienta dla aplikacji serwera znajdziesz w artykule Biblioteki klienta.
W przykładach w języku Java w tej dokumentacji założono znajomość gRPC.
Uwierzytelnianie i autoryzacja
Funkcje udostępniane przez Podróże i Postępy zamówień 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.
Konfiguracja projektu Cloud
Aby skonfigurować projekt w chmurze, najpierw utwórz go, 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żesz utworzyć wiele kont usługi, z których każde musi mieć minimalny zestaw wymaganych ról.
Postępy podróży i zamówienia mają te role:
Rola | Opis |
---|---|
Użytkownik Fleet Engine Consumer SDK
roles/fleetengine.consumerSdkUser |
Przyznaje 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 aplikacji do wspólnych przejazdów lub dostawy. |
Użytkownik pakietu Fleet Engine Driver SDK
roles/fleetengine.driverSdkUser |
Zezwala na aktualizowanie lokalizacji i tras pojazdów oraz pobieranie informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z urządzeń mobilnych w aplikacji do wspólnych przejazdów lub dostawcy. |
Superużytkownik usługi Fleet Engine roles/fleetengine.serviceSuperUser |
Przyznaje uprawnienia do wszystkich interfejsów API pojazdów i podróży. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z serwerów backendu. |
Na przykład utwórz konto usługi dla każdej z tych 3 ról i przypisz do nich 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 SDK sterowników i konsumenta opierają się na tych standardowych rolach.
Możesz też tworzyć role niestandardowe umożliwiające łączenie ze sobą dowolnego zestawu uprawnień. Pakiety SDK sterowników i konsumenckich pakietów SDK wyświetlają komunikaty o błędach, gdy brakuje wymaganego uprawnienia. Dlatego zdecydowanie zalecamy używanie przedstawionego powyżej standardowego zestawu ról i nieużywanie ról 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 bezpiecznie je podpisuje.
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 wysyłanych z odcinka 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) musisz utworzyć bezpośrednio w bazie kodu. Wymaga to dogłębnej wiedzy na temat tokenów JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.
W Fleet Engine tokeny internetowe JSON (JWT) umożliwiają krótkotrwałe uwierzytelnianie i umożliwiają urządzeniom modyfikowanie tylko pojazdów, podróży lub zadań, do których są autoryzowane. 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 roszczenia zawiera takie informacje jak czas utworzenia tokena, czas życia tokena, usługi, do których ma on dostęp, i inne informacje autoryzacji umożliwiające ograniczenie dostępu, np. identyfikator pojazdu.
Sekcja nagłówka JWT zawiera te pola:
Pole | Opis |
---|---|
alg | Algorytm, który ma zostać użyty. „RS256”. |
typ | Typ tokena. JWT. |
dziecko | Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` 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 konta usługi. |
zast. | Adres e-mail konta usługi. |
j.a. | SERVICE_NAME konta usługi, w tym przypadku https://fleetengine.googleapis.com/ |
Iat | Sygnatura czasowa utworzenia tokena wyrażona w sekundach, które upłynęły od godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Odczekaj 10 minut, aż się przechyli. Jeśli sygnatura czasowa przypada w 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 godziny 00:00:00 czasu UTC 1 stycznia 1970 roku. Żądanie nie powiedzie się, jeśli sygnatura czasowa wybiega za więcej niż godzinę. |
autoryzacja | W zależności od przypadku użycia może zawierać parametry „vehicleid” lub „tripid”. |
Utworzenie tokena JWT dotyczy jego podpisania. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz w sekcji 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.
deklaracje JWT
Podczas tworzenia ładunku JWT dodaj w sekcji autoryzacji dodatkowe zadeklarowanie z kluczem vehicleid
lub tripid
ustawionym na wartość identyfikatora pojazdu lub podróży, w którego przypadku wykonywane jest wywołanie.
Pakiet SDK kierowcy zawsze używa żądania vehicleid
niezależnie od tego, czy działa w podróży czy w pojeździe. Przed modyfikacjami system backendu Fleet Engine zapewnia, że pojazd jest powiązany z żądaną podróżą.
Pakiet SDK dla klientów indywidualnych zawsze używa roszczenia tripid
.
Dostawca wspólnych przejazdów lub dostawca powinien użyć parametru 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 są wymagane, co może uprościć implementację podpisywania tokenów.
Przypadki użycia tokena JWT
Poniżej znajdziesz przykładowy token 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 znajdziesz przykładowy token 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 roku. Odczekaj 10 minut, aż się przechyli. Jeśli sygnatura czasowa przypada w przeszłości lub w przyszłości, serwer może zgłosić błąd. - W polu
exp
użyj sygnatury czasowej wygaśnięcia tokena, podanej w sekundach 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, pamiętaj, aby użyć konta usługi jako roli sterownika lub pakietu SDK klienta. W przeciwnym razie urządzenie mobilne będzie mogło zmienić stan, którego nie powinno.
Podobnie, gdy podpisujesz token JWT, który ma być używany do wywołań uprzywilejowanych, użyj konta usługi z rolą superużytkownika. W przeciwnym razie operacja się nie powiedzie.
Generowanie tokena JWT na potrzeby testowania
Wygenerowanie 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 zawartością podaną poniżej. Właściwość iat
to bieżący czas w sekundach po epoce. Można go pobrać, uruchamiając w terminalu date +%s
. Właściwość exp
to czas ważności 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 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 standardzie Base64 powinien być teraz przechowywany w pliku signed_token.jwt
. Token jest ważny przez następną godzinę.
Teraz możesz przetestować token, uruchamiając polecenie curl
w punkcie końcowym Wyświetlenie pojazdów typu 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 śledzić oddzielnie kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawca usług dostawy tworzy pojazd za pomocą identyfikatora dostawcy (który musi być taki sam jak identyfikator projektu Google Cloud, który zawiera konto usługi używane do wywoływania interfejsów API Fleet Engine), oraz identyfikator pojazdu należącego do dostawcy wspólnych przejazdów lub dostawcy dostawy.
Pojazd, który nie był aktualizowany za pomocą usługi UpdateVehicle
w ciągu 7 dni, zostanie automatycznie usunięty. Podczas wywoływania funkcji CreateVehicle
przy użyciu istniejącej pary identyfikator dostawcy/identyfikator pojazdu wystąpił błąd. W przypadku pojazdów, które nie są często aktualizowane, można rozwiązać ten problem na 2 sposoby: często wywołując metodę CreateVehicle
z oczekiwaną parą identyfikatora dostawcy/identyfikatora pojazdu oraz odrzucając błąd, jeśli pojazd już istnieje, lub wywołanie CreateVehicle
po wystąpieniu elementu UpdateVehicle
zwracającego błąd NOT_FOUND
.
Aktualizacje lokalizacji pojazdów
Aby uzyskać najlepszą wydajność Fleet Engine, zapewnij jej strumień aktualizacji lokalizacji pojazdów. Aby zapewnić aktualizacje, skorzystaj z jednego z tych sposobów:
- Użyj pakietu SDK sterownika – Android, iOS – najprostszy sposób.
- Użyj kodu niestandardowego, który jest przydatny, jeśli lokalizacje są przekazywane przez Twój backend lub używasz urządzeń innych niż Android lub iOS.
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 kryterium filtrowania w SearchVehicles
i ListVehicles
.
Jeśli kategoria jest ustawiona na AUTO
, TWO_WHEELER
, BICYCLE
lub PEDESTRIAN
, wszystkie wyznaczanie tras pojazdów będzie korzystać z odpowiedniego elementu RouteTravelMode
.
Jeśli kategoria jest ustawiona na TAXI
lub TRUCK
, routing jest traktowany tak samo jak tryb AUTO
.
Atrybuty pojazdu
Element Pojazd zawiera powtórzone pole VehicleAttribute
. Fleet Engine nie interpretuje tych atrybutów. Interfejs SearchVehicles
API zawiera pole, które wymaga, aby pasujący element Vehicles
zawierał wszystkie uwzględnione atrybuty ustawione na określoną wartość.
Pamiętaj, że pole atrybutu jest dodatkiem do 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
Encja Pojazd zawiera powtórzone pole TripWaypoint
(RPC | REST) o nazwie waypoints
(RPC | REST).
To pole obejmuje pozostałe punkty na trasie podróży, w kolejności, w jakiej pojazd do nich dotrze. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je, gdy podróże zmieniają stan.
Te punkty na drodze są identyfikowane za pomocą pola TripId
i pola WaypointType
.
Rozszerzenie możliwości dopasowania pojazdu
Zwykle za dopasowywanie próśb o podróż do pojazdów odpowiadają zwykle usługi wspólnych przejazdów lub dostawcy usług dostawy. Usługa może korzystać z atrybutów pojazdu, aby uwzględnić pojazd w większej liczbie wyszukiwań. Na przykład dostawca 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
kwalifikować się do korzystania ze wszystkich 3 produktów. Gdy Fleet Engine otrzyma prośbę o podróż wymagającą srebrnego poziomu, wyszukiwanie będzie uwzględniać ten pojazd.
Wykorzystanie atrybutów w ten sposób 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 ma wartość. Nie można aktualizować tylko pojedynczego atrybutu.
Druga metoda to UpdateVehicleAttributes
API. 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ływania Fleet Engine. Pamiętaj, że chociaż wiele kont usługi może mieć dostęp do Fleet Engine dla tego samego dostawcy wspólnych przejazdów lub dostawcy dostawy, Fleet Engine obecnie nie obsługuje kont usługi z wielu projektów Google Cloud uzyskujących dostęp do tego samego zasobu Vehicles
.
Obiekt Vehicle
można utworzyć w stanie OFFLINE
lub ONLINE
. Jeśli utworzysz ONLINE
, może on zostać natychmiast zwrócony w odpowiedzi na zapytania SearchVehicles
.
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
.
Więcej informacji o polu typu pojazdu znajdziesz w sekcji Typy pojazdów.
Więcej informacji 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
Więcej informacji znajdziesz w dokumentacji 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 platformy Google Cloud dotyczące tworzenia pojazdów
Po otrzymaniu wywołania do punktu końcowego CreateVehicle
interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym elemencie 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 wydrukować 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
Po utworzeniu nowego pojazdu interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać te powiadomienia, postępuj zgodnie z instrukcjami podanymi tutaj.
PORADNIK: Aktualizowanie lokalizacji pojazdu
Jeśli nie używasz pakietu SDK kierowcy do aktualizacji lokalizacji pojazdu, możesz nawiązać bezpośrednie połączenie do Fleet Engine z informacjami o lokalizacji pojazdu. W przypadku każdego aktywnego pojazdu Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę i nie częściej niż co 5 sekund. 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.
PORADNIK: aktualizacja innych pól dotyczących pojazdów
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.
Pole UpdateVehicleRequest
zawiera element update_mask
wskazujący, które pola mają zostać zaktualizowane. Działanie tego pola jest takie jak w dokumentacji Protobuf dla masek pól.
Jak wspomnieliśmy w sekcji Atrybuty pojazdu, zaktualizowanie pola attributes
wymaga zapisania wszystkich atrybutów, aby zostały zachowane. Nie można 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 aktualizacji pojazdów w Google Cloud
Po otrzymaniu wywołania do punktu końcowego UpdateVehicle
interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle
. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym elemencie 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ć te powiadomienia, postępuj zgodnie z instrukcjami podanymi tutaj.
PORADNIK: Wyszukiwanie pojazdów
Fleet Engine obsługuje wyszukiwanie pojazdów. Interfejs SearchVehicles
API pozwala znaleźć w pobliżu dostępnych kierowców, którzy najlepiej sprawdzą się w takich zadaniach jak obsługa przejazdu czy zamawianie dostawy. Interfejs SearchVehicles
API zwraca listę kierowców, którzy pasują do atrybutów zadań i atrybutów pojazdów w Twojej flocie. Aby dowiedzieć się więcej, zobacz Wyszukiwanie kierowców w pobliżu.
Przykład
Podczas wyszukiwania dostępnych pojazdów Fleet Engine domyślnie wyklucza pojazdy biorące udział w aktywnych trasach. Usługi Dostawcy wspólnych przejazdów lub dostawy muszą wyraźnie uwzględniać je w żądaniach wyszukiwania. Poniższy przykład pokazuje, 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 Jakarta.
powłoka
Najpierw zaktualizuj lokalizację pojazdu, który utworzyliśmy w poprzednich krokach, aby się kwalifikował. W rzeczywistości by to zrobić za pomocą pakietu SDK kierowcy działającego na urządzeniu z Androidem lub iOS w pojeździe.
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ć 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 według atrybutów pojazdu za pomocą zapytania filtra. Składnię zapytań filtrów znajdziesz tutaj: AIP-160.
Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie według atrybutów pojazdu i nie można ich używać w przypadku innych pól. Zapytanie filtra działa jako klauzula AND
z innymi ograniczeniami, takimi jak minimum_capacity
lub vehicle_types
w SearchVehiclesRequest
.
PORADNIK: Wyświetlanie listy pojazdów
System SearchVehicles
jest zoptymalizowany pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w kolejności rankingowej i służy głównie do znajdowania w pobliżu kierowców najlepiej pasujących do danego 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ł stworzony właśnie 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 listę pojazdów w projekcie, które spełniają niektóre wymagania.
Aby dowiedzieć się, jak filtrować dane według atrybutów pojazdu, zapoznaj się z sekcją Zapytania o filtrowanie 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 jest odpowiedzialny 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 jednostek Podróży, przesyłanie żądań informacji, wyszukiwanie oraz aktualizowanie.
Element Trip
ma pole stanu, które umożliwia śledzenie postępu jego 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 TripStatus dla REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Usługa może zaktualizować podróż do: CANCELED
z jednego z tych stanów.
Gdy usługa tworzy podróż, wyszukiwarka ustawia stan na NEW
. Pole vehicle_id
jest opcjonalne. 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 „aktywna”, 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óż w drodze, stan Podróży musi być ustawiony na NEW
lub CANCELED
przed zmianą lub usunięciem vehicle_id
.
Stan ma znaczenie przy wdrażaniu obsługi kolejnych podróży. Ta obsługa umożliwia Dostawcy przypisanie nowej podróży do Pojazdu, gdy Pojazd jest w aktywnej podróży. Kod tworzenia 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 tym artykule.
Pozostałe punkty na trasie
Encja Podróż zawiera pole TripWaypoint
(RPC | REST) o nazwie remainingWaypoints
(RPC | REST).
To pole obejmuje wszystkie punkty na trasie, które pojazd musi przebyć w określonej kolejności, zanim będzie ostatni punkt docelowy tej podróży. Oblicza się na podstawie pozostałych punktów na trasie pojazdu.
W przypadku obejmujących wszystkie trasy i w przypadku podwożenia lista zawiera punkty pośrednie z innych podróży, które zostaną pokonane przed tą podróżą, ale nie zawiera żadnych punktów pośrednich
po niej. Punkt pośredni na liście jest identyfikowany przez oznaczenia TripId
i WaypointType
.
Związek między stanem podróży a pozostałymi punktami pośrednimi pojazdów
Pozostałe punkty na trasie 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 na trasie 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 będzie nadal 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 z punktu odbioru pojazdu.
Tak samo jest w przypadku ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Gdy jest to 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 wskazuje następny punkt pośredni.
Gdy stan podróży zmieni się 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: Tworzenie podróży
Aby każde żądanie podróży było śledzone i dopasowane do pojazdów we flocie, należy utworzyć element Trip
. Aby utworzyć podróż, użyj punktu końcowego CreateTrip
z CreateTripRequest
.
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 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 w tym samym pojeździe (SHARED
) lub tylko jedna grupa (EXCLUSIVE
) mogą uczestniczyć inni pasażerowie z innego miejsca wylotu i celu podróży.pickup_point
– TerminalLocation wskazuje punkt początkowy podróży. Więcej informacji znajdziesz w dokumentacji RPC lub dokumentacji REST.
Podczas tworzenia podróży możesz podać atrybuty number_of_passengers
, dropoff_point
i vehicle_id
. Chociaż te pola nie są wymagane, jeśli je podasz, zostaną zachowane. Wszystkie pozostałe pola Podróże są ignorowane. Na przykład wszystkie podróże zaczynają się od trip_status
o wartości NEW
, nawet jeśli w żądaniu utworzenia podasz trip_status
o wartości CANCELED
.
Przykład
Poniższy przykład pokazuje wycieczkę do centrum handlowego Grand Indonesia East. Ta podróż jest przeznaczona tylko dla 2 pasażerów. Wartość provider_id
obiektu 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 dopasowuje podróż do pojazdu, usługa może wywołać UpdateTrip
i zmienić vehicle_id
, gdy podróż jest 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ę do 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 platformy Google Cloud dotyczące tworzenia podróży
Po odebraniu wywołania do 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
.
PORADNIK: Aktualizowanie podróży
Element Podróż zawiera pola, które umożliwiają śledzenie przez usługę i raportowanie postępów podróży za pomocą pakietu Driver SDK i pakietu Consumer SDK. Aby zaktualizować właściwości, użyj wiadomości UpdateTripRequest
. Spowoduje to zaktualizowanie pól Podróż zgodnie z field_mask
żądania.
Zapoznaj się z UpdateTripRequest.
Dostawca wspólnych przejazdów jest odpowiedzialny za aktualizowanie tych atrybutów:
- Stan podróży.
- Identyfikator pojazdu. Podczas tworzenia lub po dopasowaniu pojazdu do podróży.
- zmian dotyczących odbioru, miejsca wylotu lub punktów pośrednich;
Fleet Engine automatycznie aktualizuje te pola podczas korzystania z funkcji udostępniania trasy za pomocą pakietu Driver SDK lub Consumer SDK:
- Trasy
- Szacowany czas dotarcia
- Pozostała odległość
- Lokalizacja pojazdu
- Pozostałe punkty na trasie
Sprawdź Trip
w RPC lub Resource.Trip
w REST.
Logi aktualizacji podróży dotyczące Google Cloud Platform
Po odebraniu wywołania do 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ć też informacje o zwróconym obiekcie 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 wyświetla pełnej historii wszystkich Podróży.
SearchTrips
to elastyczny interfejs API, ale na liście poniżej uwzględniono 2 przypadki użycia.
Określanie aktywnych podróży pojazdu – dostawca może określić aktywne podróże pojazdu. W
SearchTripsRequest
parametrvehicle_id
jest ustawiony na dany pojazd, aactive_trips_only
– natrue
.Uzgadnianie dostawcy i stanu Fleet Engine – dostawca może użyć
SearchTrips
, aby zapewnić zgodność stanu podróży z Fleet Engine. Jest to szczególnie ważne w przypadku elementu TripStatus. Jeśli stan podróży przypisanej do Pojazdu nie jest prawidłowo ustawiony naCOMPLETE
lubCANCELED
,SearchVehicles
nie uwzględnia pojazdu.
Aby korzystać z funkcji SearchTrips
w ten sposób, pozostaw pole vehicle_id
puste, ustaw w polu active_trips_only
wartość true
, a w polu minimum_staleness
ustaw czas dłuższy niż w większości przypadków.
Możesz na przykład użyć jednej godziny. Wyniki obejmują podróże, które nie są UKOŃCZONE lub ANULOWANE i nie zostały zaktualizowane w ciągu godziny. Dostawca powinien sprawdzić te Podróże, by upewnić się, że ich status 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ć funkcję CreateTrip
, która zwraca kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednia prośba została spełniona przed DEADLINE_EXCEEDED
. Więcej informacji o obsłudze błędów podróży dla Androida i iOS znajdziesz w przewodnikach po interfejsie Consumer API.
Pomoc w zakresie przejazdów Carpool
Do pojazdu obsługującego usługę TripType.SHARED
możesz przypisać kilka podróży SHARED
.
Musisz określić kolejność wszystkich bezprzejazdów w przypadku wszystkich podróży przypisanych do pojazdu w ramach tego wspólnego przejazdu za pomocą Trip.vehicle_waypoints
, gdy przypisujesz element vehicle_id
do wspólnej podróży (w żądaniu CreateTrip
lub UpdateTrip
).
Sprawdź vehicle_waypoints
– RPC lub vehicleWaypoints
– REST.
Obsługa wielu miejsc docelowych
Określ pośredni punkt docelowy
Pole intermediateDestinations
i pole intermediateDestinationIndex
w podróży (RPC | REST) zostaną połączone, aby wskazać miejsce docelowe.
Aktualizacja pośredniego miejsca docelowego
Pośrednie miejsca docelowe 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 już zostały wyświetlone, a nie tylko te, które zostały dodane lub zmodyfikowane.
Gdy intermediateDestinationIndex
wskazuje indeks po pozycji nowo dodanego/zmodyfikowanego pośredniego miejsca docelowego, nowe/zaktualizowane pośrednie miejsce docelowe nie zostanie dodane do indeksu waypoints
pojazdu ani remainingWaypoints
podróży.
Przyczyną jest to, że wszystkie pośrednie miejsca docelowe 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 upłynął punkt docelowy. Wybrane pośrednie miejsce docelowe jest określane w polu intermediateDestinationIndex
.
Gdy tripStatus
(RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, liczba z zakresu
[0..N-1] wskazuje, przez jaki pośredni punkt docelowy pojazd przejedź przez pojazd.
Gdy tripStatus
to ARRIVED_AT_INTERMEDIATE_DESTINATION, liczba z zakresu
[0..N-1] wskazuje, w którym miejscu docelowym pośrednim znajduje się pojazd.
Przykład
Poniższy przykładowy kod pokazuje, jak zaktualizować stan podróży, aby pokierować nią do pierwszego miejsca docelowego pośredniego przy założeniu, że masz utworzoną podróż obejmującą wiele miejsc docelowych i minęła już 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 używa 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 dla swojego projektu 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ć w interfejsie Fleet Engine API uprawnienia do publikowania na ten temat. Aby to zrobić, kliknij utworzony przed chwilą temat i dodaj nowe uprawnienia. 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
.
Aby skonfigurować w projekcie Cloud opcję 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"
}
}
}