Pierwsze kroki z Fleet Engine

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:

  1. Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
  2. 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:

RolaOpis
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:

PoleOpis
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:

PoleOpis
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 polu private_key_id pliku JSON konta usługi.
  • W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_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ść to iat + 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:

  1. Użyj pakietu SDK sterownika – Android, iOS – najprostszy sposób.
  2. 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ź Tripw 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 parametr vehicle_id jest ustawiony na dany pojazd, a active_trips_only – na true.

  • 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 na COMPLETE lub CANCELED, 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"
    }
  }
}