Interfejs Fleet Engine On-demand Rides and Deliveries API umożliwia zarządzanie podróżami i stan pojazdu dla aplikacji dotyczących podróży i postępu realizacji zamówień. Obsługuje transakcje między pakietem Driver SDK, pakietem Consumer SDK usługa backendu, która może komunikować się z Fleet Engine przez gRPC lub REST.
Wymagania wstępne
Na potrzeby programowania musisz zainstalować Cloud przez pakiet SDK (gcloud) i są uwierzytelnieni w do swojego projektu.
powłoka
gcloud auth login
Powinien wyświetlić się komunikat o powodzeniu, taki jak:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Sprawdź, czy interfejsy API usługi Fleet Engine w rozwiązaniu na żądanie dotyczące przejazdów i dostarczania na żądanie są prawidłowo skonfigurowane.
powłoka
gcloud --project=project-id services enable fleetengine.googleapis.com
Jeśli to polecenie spowoduje błąd, skontaktuj się z administratorem projektu i z przedstawicielem zespołu pomocy Google.
Logowanie
Flota Engine może zapisywać komunikaty logu dotyczące odbieranych wywołań interfejsu API w logach Google Cloud Platform. Zapoznaj się z dokumentacją Cloud Logging, aby dowiedzieć się więcej Omówienie sposobu odczytywania i analizowania logów.
Logowanie może być domyślnie wyłączone w przypadku projektów utworzonych przed 10 lutego 2022 r. Zobacz dokumentacja logowania .
Biblioteki klienta
Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te pomogą zwiększyć wygodę programistów w porównaniu do nieprzetworzonych plików REST czy gRPC. Aby uzyskać instrukcje dotyczące uzyskiwania bibliotek klienta dla aplikacji serwerowej, zobacz Biblioteki klienta.
W przykładach w Javie w tej dokumentacji zakładamy, że znasz gRPC.
Uwierzytelnianie i autoryzacja
Możesz skonfigurować funkcje zapewniane przez opcję Podróż i Postęp realizacji zamówienia w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON, zostały podpisane przy użyciu kont usługi utworzonych z Konsola Cloud.
Konfigurowanie projektu Cloud
Aby skonfigurować projekt w chmurze, najpierw go utwórz, a potem tworzyć 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 API Local Rides i Deliveries.
Konta usługi są powiązane z co najmniej 1 rolą. Służą do tworzenia Tokeny internetowe JSON, które przyznają różne zestawy uprawnień w zależności od role. Aby zmniejszyć ryzyko nadużyć, zazwyczaj można utworzyć wiele kont usługi, każde z minimalnym wymaganym zestawem ról.
Działania związane z podróżą i zamówieniem są powiązane z tymi rolami:
Rola | Opis |
---|---|
Użytkownik pakietu konsumenckiego pakietu SDK Fleet Engine
roles/fleetengine.consumerSdkUser |
Przyznaje uprawnienia do wyszukiwania pojazdów i pobierania informacji na temat pojazdów i podróży. Tokeny utworzone przez konto usługi z tym identyfikatorem są zwykle używane podczas wspólnych przejazdów lub do dostawy produktów na urządzeniach mobilnych. |
Użytkownik pakietu SDK Fleet Engine Driver
roles/fleetengine.driverSdkUser |
Przyznaje uprawnienia do aktualizowania lokalizacji i tras pojazdów w celu pobierania informacji o pojazdach i podróżach. Utworzone tokeny przez konto usługi z tą rolą są zwykle używane z wspólnych przejazdów czy aplikacji kierowców na urządzeniach mobilnych. |
Administrator Fleet Engine na żądanie
roles/fleetengine.ondemandAdmin |
Przyznaje uprawnienia do odczytu i zapisu wszystkich zasobów pojazdu i podróży. Podmioty zabezpieczeń z tą rolą nie muszą używać tokenów JWT – zamiast tego powinny użyć domyślnego uwierzytelniania aplikacji. Niestandardowe żądania JWT są ignorowane. Ta rola powinna być ograniczona do zaufanych środowisk (backendu klienta). |
roles/fleetengine.serviceSuperUser |
Przyznaje uprawnienia do wszystkich interfejsów API związanych z pojazdami i podróżami. Wygenerowane tokeny
przez konto usługi z tą rolą są zwykle używane z backendu
serwerów. Ta rola została wycofana. Preferowane
roles/fleetengine.ondemandAdmin . |
Na przykład utwórz konto usługi dla każdej z 3 ról i przypisz swoją rolę.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Pakiety sterowników i pakietów SDK dla klientów indywidualnych opierają się na tych standardowych rolach.
Możesz też utworzyć role niestandardowe, które pozwolą Ci dowolnego zestawu uprawnień, które można połączyć w pakiet. Pakiety SDK sterowników i klientów indywidualnych będą wyświetlać komunikaty o błędach za każdym razem, brakuje wymaganych uprawnień. Dlatego zdecydowanie zalecamy używając standardowego zestawu ról przedstawionych powyżej, a nie ról niestandardowych.
Jeśli chcesz utworzyć tokeny JWT dla niezaufanych klientów, dodaj do użytkowników z rolą 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
uwierzytelnić przy użyciu gcloud (gcloud auth list
--format='value(account)'
).
Biblioteka uwierzytelniania Fleet Engine
Fleet Engine używa tokenów sieciowych JSON (JWT), aby ograniczyć dostęp do Interfejsy Fleet Engine API. Nowa biblioteka uwierzytelniania Fleet Engine dostępne na GitHubie, upraszcza tworzenie tokenów JWT Fleet Engine i bezpieczne ich podpisywanie.
Biblioteka zapewnia te korzyści:
- Upraszcza proces tworzenia tokenów Fleet Engine.
- Zapewnia mechanizmy podpisywania tokenami inne niż pliki danych logowania (np. podszywa się pod konto usługi).
- Dołącza podpisane tokeny do żądań wychodzących wysyłanych z atrapy gRPC lub klient GAPIC.
Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji
Jeśli nie używasz biblioteki uwierzytelniania Fleet Engine, tokeny internetowe JSON (JWT) muszą być utworzone bezpośrednio w bazie kodu. Aby to zrobić, musisz mieć Omówienie tokenów JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.
Tokeny internetowe JSON (JWT) we Fleet Engine zapewniają uwierzytelnianie krótkotrwałe oraz zapewnić, że urządzenia mogą modyfikować wyłącznie pojazdy, podróże i zadania w celach do których ma upoważnienie. 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 szyfrowanie algorytmem bezpieczeństwa. Sekcja dotycząca roszczeń zawiera takie informacje jak: czas utworzenia tokena, czas życia tokenów, usługi zgłaszania praw do informacji o dostępie i innych informacji dotyczących upoważnienia w zakresie ograniczonym dostęp; np. identyfikator pojazdu.
Sekcja nagłówka JWT zawiera te pola:
Pole | Opis |
---|---|
Alg | Algorytm, który ma być używany. „RS256”. |
typ | Typ tokena. JWT. |
dziecko | Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` pliku JSON konta usługi. Pamiętaj, aby użyć klucza z konta usługi o odpowiednim poziomie uprawnień. |
Sekcja deklaracji JWT zawiera te pola:
Pole | Opis |
---|---|
Iss | Adres e-mail konta usługi. |
zast. | Adres e-mail konta usługi. |
Aud | Twoje konto usługi to SERVICE_NAME, w tym przypadku https://fleetengine.googleapis.com/ |
Iat | Sygnatura czasowa określająca, kiedy token został utworzony, wyrażony w sekundach. od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa w przeszłości lub w przyszłości, serwer może zgłosić błąd. |
eksperyment | Sygnatura czasowa wygaśnięcia tokenu podana w sekundach od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Żądanie nie powiedzie się, jeśli sygnatura czasowa to za więcej niż godzinę. |
autoryzacja | W zależności od przypadku użycia może zawierać parametr „vehicleid” lub „tripid”. |
Utworzenie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz tutaj Autoryzacja konta usługi bez protokołu OAuth. Następnie możesz dołączyć podpisany token do wywołań gRPC lub innych używanych metod aby uzyskać dostęp do Fleet Engine.
Żądania JWT
Podczas tworzenia ładunku JWT dodaj dodatkową deklarację w autoryzacji
z kluczem vehicleid
lub tripid
ustawionym na wartość klucza
identyfikator pojazdu lub identyfikator podróży, którego dotyczy połączenie.
Pakiet Driver SDK zawsze używa twierdzenia vehicleid
, niezależnie od tego, czy działa
podróż lub pojazd. Backend Fleet Engine zapewnia, że pojazd
jest powiązana z żądaną podróżą przed wprowadzeniem zmiany.
Pakiet SDK klienta zawsze używa roszczenia tripid
.
Dostawca wspólnych przejazdów lub dostawca usług dostawy powinien użyć karty vehicleid
lub tripid
ze znakiem „*” do
pasują do wszystkich kategorii Pojazdy i Podróże. Pamiętaj, że token JWT może zawierać oba tokeny:
nawet jeśli nie jest wymagana, może to uprościć implementację podpisywania tokenów.
Przypadki użycia JWT
Poniżej znajdziesz przykładowy token dla opcji Serwer dostawcy:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Poniżej znajdziesz przykładowy token dla aplikacji konsumenta:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Poniżej znajdziesz przykładowy token dla aplikacji sterownika:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- W polu
kid
w nagłówku podaj klucz prywatny konta usługi ID. Tę wartość znajdziesz w poluprivate_key_id
swojej usługi plik JSON konta. - W polach
iss
isub
podaj adres e-mail konta usługi. Tę wartość znajdziesz w poluclient_email
na koncie usługi Plik JSON. - W polu
aud
wpisz https://SERVICE_NAME/. - W polu
iat
użyj sygnatury czasowej utworzenia tokena, określony jako czas, który upłynął od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa w przeszłości, lub w przyszłości serwer może zgłosić błąd. - W polu
exp
użyj sygnatury czasowej, gdy token wygaśnie, określona jako sekundy od 00:00:00 czasu UTC, 1 stycznia 1970 r. Maksymalna wartość dozwolona wartość toiat
+ 3600.
Podczas podpisywania tokena JWT, który ma być przekazany na urządzenie mobilne, użyj funkcji konto usługi z rolą Driver lub Consumer SDK. W przeciwnym razie funkcja będzie mieć możliwość zmiany stanu, którego nie powinna mieć.
Podobnie podczas podpisywania tokena JWT, który ma być używany w wywołaniach z podwyższonymi uprawnieniami, upewnij się też, aby używać konta usługi z rolą superużytkownika. W przeciwnym razie nie powiedzie się.
Generowanie tokena JWT na potrzeby testowania
Generowanie tokenów z terminala może być pomocne podczas testowania.
Aby wykonać te czynności, użytkownik konto 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ą. iat
jest wartością bieżącą czasu w sekundach po epoce. Może ona być
pobrane przez uruchomienie w terminalu date +%s
. Właściwość exp
to
czas wygaśnięcia w sekundach po epoce, który można obliczyć za pomocą
Dodaję 3600 do iat
. Czas wygaśnięcia nie może przekraczać godziny w
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 zespołu Super Konto usługi uż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
W pliku powinien być teraz przechowywany podpisany token JWT zakodowany w standardzie Base64
signed_token.jwt
Token będzie ważny przez następną godzinę.
Możesz teraz przetestować token, uruchamiając polecenie curl
dla listy pojazdów
Punkt końcowy REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Pojazdy i ich cykl życia
Pojazd to podmiot reprezentujący parę kierowca–pojazd. Obecnie Nie można śledzić oddzielnie kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawca usług dostawy tworzy Pojazd przy użyciu identyfikatora dostawcy (musi być taki sam jak Identyfikator projektu Google Cloud zawierającego konto usługi używane do wywoływania interfejsów Fleet Engine API) i identyfikatora pojazdu należącego do dostawcy wspólnych przejazdów lub dostawcy usług dostawy.
Pojazd, który nie został zaktualizowany przez UpdateVehicle
po 7 dniach,
zostanie automatycznie usunięta, a przypisane do niej podróże, jeśli są, zostaną oznaczone jako
nieprzypisane. Zalecane metody utrzymania dostępności pojazdu
we Fleet Engine jest regularne aktualizowanie swojej lokalizacji. Aktualizacje do większości
innych pól w elemencie Vehicle
też przedłuży swoją żywotność, pod warunkiem że
wartość nowego pola jest inna niż wartość w dotychczasowym polu;
UWAGA: niektóre pola w elemencie Vehicle
, np. device_settings
, mają charakter czysto debugowany.
informacje, które nie są utrwalone przez Fleet Engine. Nie spowoduje to ich aktualizacji
przedłużyć żywotność elementu Vehicle
.
Podczas wywoływania funkcji CreateVehicle
przy użyciu:
Para identyfikatora dostawcy i identyfikatora pojazdu, która już istnieje. Sprawa samochodów,
które nie są często aktualizowane. Można sobie z nimi radzić na 2 sposoby: często dzwoniący
CreateVehicle
z oczekiwanym identyfikatorem dostawcy/identyfikatorem pojazdu i odrzuceniem
błąd, jeśli pojazd już istnieje; lub dzwoniąc pod numer CreateVehicle
po
UpdateVehicle
zwraca błąd NOT_FOUND
.
Aktualizacje lokalizacji pojazdu
Aby uzyskać najlepszą wydajność we Fleet Engine, zapewnij jej strumień pojazdów aktualizacje lokalizacji. Zaktualizuj informacje na jeden z tych sposobów:
- Użyj pakietu Driver SDK – Android iOS – najprostsza opcja.
- Użyj kodu niestandardowego – przydatny, jeśli lokalizacje są przekazywane przez backend, lub jeśli używasz urządzeń innych niż Android iOS.
Rodzaj pojazdu
Pole „Pojazd” zawiera wymagane pole VehicleType
, które zawiera znak
wyliczenie Category
, które może być określone jako AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
lub PEDESTRIAN
. Typ pojazdu może służyć jako
kryteria filtrowania w kolumnach SearchVehicles
i ListVehicles
.
Wszystkie trasy dla pojazdów będą używać odpowiedniej wartości RouteTravelMode
, jeśli
kategoria jest ustawiona na AUTO
, TWO_WHEELER
, BICYCLE
lub PEDESTRIAN
.
Jeśli kategoria jest ustawiona na TAXI
lub TRUCK
, routing jest traktowany tak samo jak
tryb AUTO
.
Atrybuty pojazdu
Element Pojazd zawiera powtarzane pole VehicleAttribute
. Te
nie będą interpretowane przez Fleet Engine. SearchVehicles
Interfejs API zawiera pole, które wymaga, aby pasował Vehicles
musi zawierać wszystkie
zawarte atrybuty ustawione na określoną wartość.
Pamiętaj, że pole atrybutu zostało dodane do kilku innych obsługiwanych pól.
w wiadomości Vehicle
, na przykład vehicle_type
i supported_trip_types
.
Pozostałe punkty na trasie pojazdu
Element Pojazd zawiera powtarzalne pole TripWaypoint
(RPC | REST),
o nazwie waypoints
(RPC | REST).
To pole zawiera pozostałe punkty na trasie podróży w kolejności
pojazd dotrze do nich. Fleet Engine oblicza to pole, gdy podróże
przypisany do pojazdu i aktualizuje go w miarę zmiany stanu podróży.
Te punkty pośrednie można zidentyfikować za pomocą pól TripId
i WaypointType
.
Zwiększanie możliwości dopasowania pojazdu
Zwykle za dopasowanie odpowiadają zwykle usługi wspólnych przejazdów lub firm kurierskich
dla pojazdów. Usługa może wykorzystać atrybuty pojazdu, aby uwzględnić
podczas większej liczby wyszukiwań. Dostawca może na przykład zaimplementować
zestaw atrybutów odpowiadających poziomom bonusów lub możliwości oferowanych przez
pojazdem. Na przykład trzy poziomy mogą być zbiorem atrybutów z wartościami logicznymi
wartości: is_bronze_level
, is_silver_level
i is_gold_level
. Pojazd
mogą kwalifikować się
do wszystkich 3 elementów. Gdy Fleet Engine otrzyma żądanie
w podróży wymagającej zaawansowanych umiejętności, wyszukiwanie obejmuje również dany pojazd.
Użycie atrybutów w ten sposób obejmuje pojazdy oferowane w rozmaitych usługach
funkcje zabezpieczeń.
Atrybuty pojazdu można aktualizować na 2 sposoby. Jeden to UpdateVehicle
API. Podczas korzystania z tego interfejsu API cały zestaw atrybutów pojazdu jest
ustaw wartość. Nie można zaktualizować tylko jednego atrybutu.
Drugą metodą jest interfejs API UpdateVehicleAttributes
. Ta metoda zajmuje tylko
atrybuty do zaktualizowania. Atrybuty zawarte w żądaniu zostaną
ustawiona na nową wartość lub dodaną wartość; nieokreślone atrybuty nie zostaną zmienione.
INSTRUKCJA: tworzenie pojazdu
Dla każdego pojazdu, który ma być śledzony we flocie, należy utworzyć element Vehicle
.
Użyj punktu końcowego CreateVehicle
z elementem CreateVehicleRequest
, aby utworzyć
Pojazd.
Element provider_id
elementu Vehicle
musi być identyfikatorem projektu
(np. mój projekt na żądanie) projektu Google Cloud, który zawiera
Konta usługi, które będą używane do wywoływania Fleet Engine. Pamiętaj, że choć
wiele kont usługi może uzyskiwać dostęp do Fleet Engine na potrzeby tego samego wspólnych przejazdów
lub dostawcą usług dostarczania, Fleet Engine nie obsługuje obecnie kont usługi
wiele projektów Google Cloud uzyskujących dostęp do tego samego obiektu Vehicles
.
Vehicle
można utworzyć w stanie OFFLINE
lub ONLINE
. Jeśli
utworzono ONLINE
, może zostać natychmiast zwrócony w odpowiedzi na: SearchVehicles
zapytań.
Początkowe wywołanie last_location
może zostać uwzględnione w wywołaniu CreateVehicle
.
Chociaż jest to dozwolone, nie należy tworzyć typu Vehicle
w stanie ONLINE
bez
last_location
.
Szczegółowe informacje o pojeździe znajdziesz w sekcji Typy pojazdów. type (Typ konwersji).
Szczegółowe informacje znajdziesz w artykule Atrybuty pojazdu. w polu atrybutów.
Wartość zwrócona z metody CreateVehicle
to utworzony element Vehicle
.
Przykład
powłoka
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Zobacz providers.vehicles.create odwołania.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Logi Google Cloud Platform dotyczące tworzenia pojazdu
Interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud, gdy
Odebrane wywołanie punktu końcowego CreateVehicle
. Wpis logu zawiera
informacje o wartościach w żądaniu CreateVehicle
. Jeśli połączenie
będzie zawierać również informacje o Vehicle
, które zostały użyte
.
powłoka
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Powinien zostać wydrukowany rekord podobny do tego:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Powiadomienia Cloud Pub/Sub dotyczące tworzenia pojazdu
Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub, gdy nowy pojazdem. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcje znajdziesz tutaj.
INSTRUKCJA: aktualizowanie lokalizacji pojazdu
Jeśli nie używasz pakietu Driver SDK do aktualizowania lokalizacji pojazdu, możesz bezpośrednie połączenie z lokalizacją pojazdu we Fleet Engine. 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 użytkownika pakietu SDK Fleet Engine Driver uprawnień.
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 providers.vehicles.update odwołania.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
INSTRUKCJA: aktualizowanie innych pól dotyczących pojazdu
Aktualizacje innych atrybutów stanu pojazdu pojawiają się rzadziej niż
aktualizacje pozycji. Wymagane są aktualizacje atrybutów innych niż last_location
Uprawnienia superużytkownika Fleet Engine.
Pole UpdateVehicleRequest
zawiera element update_mask
wskazujący, które pola
. Działanie tego pola jest takie samo jak w dokumentacji Protobuf dla
maski pól.
Zgodnie z opisem w atrybutach pojazdu aktualizacja
Pole attributes
wymaga zapisania wszystkich atrybutów w celu zachowania. it
nie można zaktualizować tylko wartości jednej pary klucz-wartość w funkcji
UpdateVehicle
połączenie. Aby zaktualizować wartości określonych atrybutów, para klucz-wartość
Można użyć interfejsu API UpdateVehicleAttributes
.
Przykład
W tym przykładzie włączona jest funkcja back_to_back
.
powłoka
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Zobacz providers.vehicles.update odwołania.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Logi Google Cloud Platform dotyczące aktualizacji pojazdów
Interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud, gdy
Odebrane wywołanie punktu końcowego UpdateVehicle
. Wpis logu zawiera
informacje o wartościach w żądaniu UpdateVehicle
. Jeśli połączenie
będzie zawierać również informacje o Vehicle
, które zostały użyte
.
powłoka
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Powiadomienia Cloud Pub/Sub dotyczące aktualizacji pojazdów
Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub, gdy pojazd jest zaktualizowany. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcje znajdziesz tutaj.
INSTRUKCJA: wyszukiwanie pojazdów
Fleet Engine obsługuje wyszukiwanie pojazdów. SearchVehicles
Interfejs API umożliwia znajdowanie kierowców w pobliżu, którzy najlepiej pasują do danego zadania, np.
usługi przewozu osób
lub prośby o dostawę. Interfejs SearchVehicles
API zwraca błąd
rankingowa lista kierowców pasujących do atrybutów zadań i atrybutów pojazdów w
Twoją flotę. Więcej informacji:
Znajdowanie kierowców w pobliżu
Przykład
Podczas wyszukiwania dostępnych pojazdów Fleet Engine wyklucza pojazdy domyślnie aktywne podróże. Usługi dostawcy wspólnych przejazdów lub dostawy muszą: bezpośrednio uwzględniać je w żądaniach wyszukiwania. Ten przykład pokazuje, jak uwzględnia te pojazdy w wyszukiwaniu pojazdów pasujących do trasy podróży Indonesia East Mall do centrum kongresowego Balai Sidang Jakarta.
powłoka
Najpierw zaktualizuj lokalizację pojazdu, którą utworzyliśmy w poprzednich krokach, jest odpowiednia. W prawdziwym świecie robiłby to aktywny pakiet Driver SDK. 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ć przynajmniej ten pojazd.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Zobacz providers.vehicles.search odwołania.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Zapytanie dotyczące filtrowania pojazdów
SearchVehicles
i ListVehicles
obsługują filtrowanie atrybutów pojazdu
za pomocą zapytania filtra. Składnię zapytań filtra znajdziesz tutaj
AIP-160.
Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie według atrybutów pojazdu.
nie można używać w innych polach. Zapytanie filtra działa jako klauzula AND
z innymi ograniczeniami, takimi jak minimum_capacity
lub vehicle_types
w
SearchVehiclesRequest
INSTRUKCJA: wyświetlanie listy pojazdów
Witryna SearchVehicles
jest zoptymalizowana pod kątem znajdowania niewielkiej liczby pojazdów w rankingu
zamawiaj bardzo szybko. Służy głównie do znajdowania kierowców w okolicy, którzy najlepiej pasują
któreś z zadań. Czasami jednak chcesz znaleźć wszystkie pojazdy spełniające określone
, nawet jeśli konieczne jest stronicowanie wyników. ListVehicles
to
stworzonych z myślą o tych zastosowaniach.
Interfejs API ListVehicles
umożliwia znalezienie wszystkich pojazdów, które spełniają określone
opcje żądania. Interfejs API ListVehicles
zwraca podzieloną na strony listę pojazdów w:
który spełnia określone wymagania.
Aby filtrować według atrybutów pojazdu, zapoznaj się z artykułem Zapytanie filtrowania pojazdów.
Przykład
W tym przykładzie filtrujemy: vehicle_type
i atrybuty za pomocą
Ciąg tekstowy 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 providers.vehicles.list odwołania.
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ą Fleet Engine
i interfejsów. Fleet Engine zapewnia zarówno usługę RPC,
TripService
.
i zasoby REST, provider.trips
, Te interfejsy umożliwiają tworzenie elementu Podróże, wysyłanie żądań informacji, wyszukiwanie
funkcji i aktualizacji.
Element Trip
ma pole stanu, które umożliwia śledzenie postępów w cyklu życia.
Wartości zmieniają się z NEW
na COMPLETE
plus CANCELED
i UNKNOWN_TRIP_STATUS
, Informacje o RPCznajdziesz w artykule trip_status
lub TripStatus w przypadku REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Twoja usługa może zaktualizować podróż do: CANCELED
z dowolnego z tych stanów.
Gdy usługa utworzy podróż, wyszukiwarka ustawia jej stan na NEW
. O
Pole vehicle_id
jest opcjonalne. Tak jak w przypadku pojazdów, nieprzypisane przejazdy są usuwane automatycznie.
po 7 dniach bez aktualizacji. Jeśli Twoja usługa próbuje utworzyć podróż z
który już istnieje, zwracany jest błąd. Podróż jest uznawana za „aktywną”, jeśli
ma stan inny niż COMPLETE
lub CANCELED
. To rozróżnienie jest
ważne w polu active_trips
w elemencie Pojazd oraz SearchTripsRequest
.
Usługa może zmienić vehicle_id
przypisane do podróży tylko podczas podróży
jest aktywny. Możesz to zrobić na przykład wtedy, gdy kierowca anuluje podróż, kiedy
trasa, a podróż zostanie przypisana do innego pojazdu.
Stan jest ważny przy wdrażaniu jeden po drugim z pomocą w podróży. Ta pomoc umożliwia Usługodawcy przypisanie nowej trasy do pojazdu podczas gdy Pojazd jest w trakcie aktywnej podróży. Kod do utworzenia jednej podróży w drugą stronę jest taka sama jak w przypadku pojedynczej podróży identyfikatora pojazdu. Fleet Engine dodaje miejsce wylotu i cel podróży do punktów na trasie. Więcej informacji o kolejnych podróżach znajdziesz na stronie Tworzenie podróży wielopunktowych.
Pozostałe punkty na trasie
Element Trip zawiera powtarzane pole TripWaypoint
(RPC | REST),
o nazwie remainingWaypoints
(RPC | REST).
To pole obejmuje wszystkie punkty na trasie, które musi przebyć pojazd w zależności
przed ostatecznym punktem wylotu. Sposób obliczania:
Pozostałe punkty na trasie pojazdu.
W przypadkach użycia „Powrot do siebie” i „Podwożenie” ta lista zawiera punkty pośrednie od
inne przejazdy, które zostaną rozliczone przed tą podróżą, z wyłączeniem wszystkich punktów pośrednich
po podróży. Punkt pośredni na liście można rozpoznać po elemencie TripId
i WaypointType
.
Związek między stanem podróży a pozostałymi punktami na trasie pojazdu
Pozostałe punkty pośrednie pojazdu (RPC | REST) będą
zostanie zaktualizowana, gdy Fleet Engine otrzyma prośbę o zmianę stanu podróży.
poprzedni punkt pośredni zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, gdy
tripStatus
(RPC | REST)
zmienił się z innego stanu na ENROUTE_TO_XXX. Oznacza to, że gdy
stan podróży zmienia się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP,
punkt odbioru nadal będzie na liście punktów pośrednich pojazdu, ale podczas podróży
stan został zmieniony na ENROUTE_TO_INTERMEDIATE_DESTINATION lub ENROUTE_TO_DROPOFF,
jego punkt odbioru zostanie usunięty z pozostałych punktów na trasie pojazdu.
To samo dotyczy ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Gdy ARRIVED_AT_INTERMEDIATE_DESTINATION, Obecne pośrednie miejsce docelowe nie zostanie usunięte z pozostałej części pojazdu listę punktów pośrednich, dopóki pojazd nie zgłosi, że kieruje się do następnego punktu.
Po zmianie stanu podróży na COMPLETED
żadne punkty pośrednie z tej podróży nie zostaną uwzględnione
na pozostałej liście punktów pośrednich pojazdu.
INSTRUKCJA: tworzenie podróży
Aby można było śledzić każde żądanie podróży, należy utworzyć element Trip
dopasowane do pojazdów we flocie. Użyj punktu końcowego CreateTrip
z CreateTripRequest
, aby utworzyć podróż.
Do utworzenia podróży wymagane są te atrybuty:
parent
– ciąg tekstowy zawierający identyfikator dostawcy utworzony, gdy Google Projekt Cloud został utworzony.trip_id
– ciąg znaków utworzony przez dostawcę wspólnych przejazdów.trip
– kontener z podstawowymi metadanymi opisującymi podróż.trip_type
– wyliczenie określające, czy w podróży mogą brać udział inni pasażerowie. z innego miejsca wylotu i miejsca docelowego w tym samym pojeździe (SHARED
) lub tylko przez jedną stronę (EXCLUSIVE
).pickup_point
– TerminalLocation reprezentujący punkt początkowy dla podróży. Zapoznaj się z dokumentacją RPC. lub dokumentacja REST
Podczas tworzenia podróży możesz podać te dane: number_of_passengers
, dropoff_point
i vehicle_id
. Chociaż te pola nie są wymagane, jeśli je podasz,
są zachowywane. Wszystkie pozostałe pola Podróż są ignorowane. Na przykład: wszystkie podróże
zacznij od trip_status
o wartości NEW
, nawet jeśli zdasz trip_status
CANCELED
w prośbie o utworzenie.
Przykład
W poniższym przykładzie jest tworzona podróż do centrum handlowego Grand Indonesia East Mall. Podróż
jest przeznaczona dla 2 pasażerów i ma charakter wyłączny. Wartość provider_id
właściwości Trip
musi być
taki sam jak identyfikator projektu. W tym przykładzie dostawca wspólnych przejazdów utworzył
Projekt Google Cloud, project-id. Ten projekt musi mieć
Konta usługi używane do wywoływania Fleet Engine. Stan podróży to NEW
.
Później, po dopasowaniu usługi do pojazdu, usługa może nawiązać połączenie
UpdateTrip
i zmień 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 providers.trips.create odwołania.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Logi Google Cloud Platform dotyczące tworzenia podróży
Interfejs Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud, gdy
Odebrane wywołanie punktu końcowego CreateTrip
. Wpis logu zawiera
informacje o wartościach w żądaniu CreateTrip
. Jeśli połączenie
będzie zawierać również informacje o zwróconym obiekcie Trip
.
WSKAZÓWKA: aktualizowanie podróży
Element Podróż zawiera pola, które umożliwiają śledzenie przez usługę oraz
raportowania postępów w podróży przez pakiet SDK Driver SDK
pakiet SDK dla klientów indywidualnych. Aby zaktualizować właściwości, użyj komponentu UpdateTripRequest
. Spowoduje to zaktualizowanie pól Podróży zgodnie z wartością field_mask
żądania.
Zobacz UpdateTripRequest.
Dostawca wspólnych przejazdów odpowiada za aktualizację tych atrybutów:
- Stan podróży.
- Identyfikator pojazdu. W momencie utworzenia lub po dopasowaniu pojazdu do podróży.
- Zmiany dotyczące odbioru, odjazdu lub punktów pośrednich.
Fleet Engine automatycznie aktualizuje te pola, gdy używasz Funkcja udostępniania czynności za pomocą pakietu SDK Driver lub pakietu SDK dla klientów indywidualnych:
- Trasy
- Szacowany czas zakończenia
- Pozostały dystans
- Lokalizacja pojazdu
- Pozostałe punkty pośrednie
Zapoznaj się z informacjami Trip
w RPC lub
Resource.Trip
w formacie REST.
Logi Google Cloud Platform dotyczące aktualizacji podróży
Interfejs Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud, gdy
Odebrane wywołanie punktu końcowego UpdateTrip
. Wpis logu zawiera
informacje o wartościach w żądaniu UpdateTrip
. Jeśli wywołanie się powiedzie,
będzie też zawierać informacje o zwróconym obiekcie Trip
.
INSTRUKCJA: wyszukiwanie wycieczek
Fleet Engine obsługuje wyszukiwanie podróży. Jak już wspomniano, Podróż jest
są automatycznie usuwane po 7 dniach, więc SearchTrips
nie:
wyświetlić pełną historię wszystkich Podróży.
SearchTrips
to elastyczny interfejs API, ale poniższa lista uwzględnia 2 przypadki użycia.
Określanie aktywnych podróży pojazdu – Dostawca może określić obecnie aktywne podróże pojazdu. W
SearchTripsRequest
makrovehicle_id
jest ustawiony na rozważany pojazd iactive_trips_only
powinna mieć wartośćtrue
.Uzgadnianie stanu dostawcy i floty floty – Dostawca może wykorzystać
SearchTrips
, aby sprawdzić, czy stan ich podróży jest taki sam jak stan floty w Fleet Engine. Jest to szczególnie ważne w przypadku aplikacji TripStatus. Jeśli stan podróży został przypisany na Pojazd nie jest prawidłowo ustawiony naCOMPLETE
lubCANCELED
, Pojazd nie obejmuje:SearchVehicles
.
Aby użyć metody SearchTrips
w ten sposób, pozostaw pole vehicle_id
puste, ustaw active_trips_only
na true
i ustaw minimum_staleness
na czas dłuższy niż większość czasu trwania podróży.
Możesz na przykład wybrać 1 godzinę. Wyniki obejmują Podróże, które nie są
ZAKOŃCZONE ani ANULOWANE, a nie zostały zaktualizowane od ponad godziny. Dostawca
powinien sprawdzić te podróże, aby upewnić się, że ich status we Fleet Engine
zostały poprawnie zaktualizowane.
Rozwiązywanie problemów
W przypadku błędu DEADLINE_EXCEEDED
stan Fleet Engine to
nieznane. Dostawca powinien ponownie wywołać metodę CreateTrip
, która zwróci błąd
201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednie żądanie zostało uznane za uzasadnione.
przed DEADLINE_EXCEEDED
. Więcej informacji znajdziesz w przewodnikach dotyczących interfejsu Consumer API
o postępowaniu w przypadku błędów podróży: Android
lub iOS.
Obsługa podwożenia w podróży
Możesz przypisać kilka przejazdów typu SHARED
do pojazdu, który obsługuje usługę TripType.SHARED
.
Musisz określić kolejność wszystkich nieprzebytych punktów pośrednich dla wszystkich podróży przypisanych do
pojazdem w tej wspólnej przejażdżce przez: Trip.vehicle_waypoints
, gdy przypiszesz
vehicle_id
za udostępnioną podróż (w żądaniu CreateTrip
lub UpdateTrip
).
Informacje o RPCznajdziesz w artykule vehicle_waypoints
lub vehicleWaypoints
w przypadku formatu REST.
Obsługa wielu miejsc docelowych
Określ średniozaawansowane miejsce docelowe
Pole intermediateDestinations
i pole intermediateDestinationIndex
w podróży (RPC | REST)
są łączone, aby wskazać miejsce docelowe.
Zaktualizuj pośrednie miejsce docelowe
Miejsca docelowe pośrednie możesz zaktualizować w: UpdateTrip
. Podczas aktualizowania
pośrednie miejsca docelowe, podaj pełną listę miejsc pośrednich,
w tym te, które zostały już odwiedzone, a nie tylko nowe
dodane lub zmienione.
Gdy intermediateDestinationIndex
wskazuje indeks po pozycji
nowo dodane/zmodyfikowane pośrednie miejsce docelowe, nowe/zaktualizowane miejsce docelowe
cel podróży nie zostanie dodany do: waypoints
pojazdu ani remainingWaypoints
podróży.
Powodem jest to, że wszystkie miejsca docelowe pośrednie przed intermediateDestinationIndex
są traktowane jako już odwiedzone.
Zmiany stanu podróży
Pole intermediateDestinationsVersion
w (RPC | REST)
jest wymagany w żądaniu aktualizacji stanu podróży wysyłanym do Fleet Engine, aby wskazać
pośrednie miejsce docelowe minie. Docelowe pośrednie miejsce docelowe
określa się w polu intermediateDestinationIndex
.
Gdy tripStatus
(RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, wartość pomiędzy
[0..N-1] wskazuje pośrednie miejsce docelowe, przez które pojazd będzie następny.
Gdy tripStatus
to ARRIVED_AT_INTERMEDIATE_DESTINATION, wartość pomiędzy
[0..N-1] wskazuje pośrednie miejsce docelowe, na którym znajduje się pojazd.
Przykład
Ten przykładowy kod ilustruje, jak zaktualizować stan podróży, aby w trasie do pierwszego pośredniego miejsca docelowego, zakładając, że utworzysz w przypadku podróży z wieloma miejscami docelowymi, a punkt odbioru minął.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
INSTRUKCJA: subskrybowanie powiadomień z interfejsu Fleet Engine API
Fleet Engine API korzysta z Google Cloud Pub/Sub do publikowania powiadomień na temat stworzony przez klienta Google Cloud Projekt. Usługa Pub/Sub nie jest domyślnie włączona dla Fleet Engine w Twojej usłudze Google Cloud w projektach AI. Aby włączyć Pub/Sub, prześlij zgłoszenie do zespołu pomocy lub skontaktuj się z inżynierem ds. obsługi klienta.
Aby utworzyć temat w projekcie Cloud, wykonaj te instrukcje. Identyfikator tematu musi mieć wartość „fleet_engine_notifications”.
Temat musi być utworzony w tym samym projekcie Cloud, który wywołuje Fleet Engine API.
Po utworzeniu tematu musisz przyznać interfejs Fleet Engine API
do publikowania w temacie. Aby to zrobić, kliknij temat,
właśnie utworzył(a) i dodaje nowe uprawnienie. Aby otworzyć edytor uprawnień, konieczne może być kliknięcie POKAŻ PANEL INFORMACYJNY.
Podmiot zabezpieczeń powinien być geo-fleet-engine@system.gserviceaccount.com
a rolą powinien być Pub/Sub publisher
.
Aby skonfigurować projekt Cloud do subskrybowania powiadomień, wykonaj te instrukcje
Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych danych
formaty, protobuf
oraz
json
Format danych każdego powiadomienia jest określony w sekcji
Atrybuty PubsubMessage
z kluczem jako 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"
}
}
}