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 dotyczących podróży i zamówień. Obsługuje transakcje między pakietem SDK sterownika, pakietem SDK konsumenta i usługą backendu, które mogą komunikować się z Fleet Engine za pomocą wywołań gRPC lub REST.

Wymagania wstępne

Jeśli tworzysz program, zainstaluj pakiet SDK Cloud (gcloud) i uwierzytelnij się w projekcie.

gcloud auth login

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

Sprawdź, czy interfejsy Fleet Engine API dotyczące przejazdów i dostaw na żądanie są prawidłowo skonfigurowane.

gcloud --project=project-id services enable fleetengine.googleapis.com

Logowanie

Fleet Engine może zapisywać komunikaty logów o odbieranych wywołaniach interfejsu API w logach platformy Google Cloud. Informacje o tym, jak odczytywać i analizować logi, znajdziesz w dokumentacji Cloud Logging.

W przypadku projektów 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 klienckie w kilku popularnych językach programowania. Biblioteki te ułatwiają pracę programistom w porównaniu z nieprzetworzonym protokołem REST lub gRPC. Instrukcje uzyskiwania bibliotek klienta dla aplikacji serwera znajdziesz w sekcji Biblioteki klienta.

W przykładach w języku Java w tej dokumentacji założono znajomość gRPC.

Uwierzytelnianie i autoryzacja

Funkcje dostępne dla poszczególnych etapów podróży i zamówienia możesz skonfigurować w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON, które zostały podpisane przy użyciu kont usługi utworzonych w Cloud Console.

Konfigurowanie projektu w chmurze

Aby skonfigurować projekt w chmurze, najpierw utwórz projekt, a potem utwórz konta usługi.

Aby utworzyć projekt Google Cloud:

1. Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
2. Korzystając z 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 ograniczyć ryzyko nadużyć, możesz utworzyć kilka kont usługi o minimalnym zestawie ról.

W postępach podróży i zamówienia są używane następujące role:

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

Na podstawie tych standardowych ról powstają pakiety SDK sterowników i konsumentów.

Możesz też utworzyć role niestandardowe, które pozwalają łączyć ze sobą dowolny zestaw uprawnień. Za każdym razem, gdy brakuje wymaganego uprawnienia, pakiety SDK sterowników i konsumentów wyświetlają komunikaty o błędach. Dlatego zdecydowanie zalecamy używanie przedstawionego powyżej standardowego zestawu ról i unikanie ról niestandardowych.

Jeśli musisz 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 za pomocą 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 w GitHub upraszcza tworzenie tokenów JWT Fleet Engine i bezpiecznie je podpisuje.

Biblioteka zapewnia te korzyści:

• Upraszcza proces tworzenia tokenów Fleet Engine.
• Udostępnia mechanizmy podpisywania tokenów inne niż korzystanie z plików 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 sieciowe JSON (JWT) trzeba 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.

Tokeny sieciowe JSON (JWT) w Fleet Engine zapewniają krótkotrwałe uwierzytelnianie i dają pewność, że urządzenia mogą modyfikować tylko pojazdy, podróże lub zadania, do których są autoryzowane. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera takie informacje, jak klucz prywatny do użycia (uzyskany z kont usługi) i algorytm szyfrowania. Sekcja deklaracji zawiera takie informacje jak czas utworzenia tokena, czas życia tokenów, usługi, do których ma on dostęp, oraz inne informacje o autoryzacji umożliwiające zakres dostępu, na przykład identyfikator pojazdu.

Sekcja nagłówka JWT zawiera te pola:

Sekcja deklaracji JWT zawiera te pola:

Utworzenie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz w artykule Autoryzacja konta usługi bez OAuth. Potem możesz dołączyć podpisany token do wywołań gRPC lub innych metod używanych do uzyskiwania dostępu do Fleet Engine.

Żądania JWT

Podczas tworzenia ładunku JWT dodaj dodatkowe deklaracja w sekcji autoryzacji z kluczem vehicleid lub tripid ustawionym na wartość identyfikatora pojazdu lub identyfikatora podróży, w przypadku którego wykonywane jest wywołanie.

Pakiet SDK kierowcy zawsze używa deklaracji vehicleid, niezależnie od tego, czy jest używany w podróży, czy w pojeździe. Backend Fleet Engine przed modyfikacjami zapewnia, że pojazd jest powiązany z żądaną podróżą.

Pakiet SDK dla konsumentów zawsze używa deklaracji tripid.

Wspólny przejazd lub dostawca dostawy powinien używać parametru vehicleid lub tripid razem z „*”, aby dopasować wszystkie pojazdy i Podróże. Pamiętaj, że token JWT może zawierać oba tokeny, nawet jeśli nie jest on wymagany. Może to uprościć implementację podpisywania tokenów.

Przypadki użycia JWT

Poniżej znajduje się przykładowy token dla serwera dostawcy:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Poniżej znajdziesz przykładowy token aplikacji konsumenta:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Poniżej znajduje się przykładowy token dla aplikacji Driver:

{
  "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 w pliku JSON konta usługi.
• W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email w pliku JSON konta usługi.
• W polu aud podaj https://SERVICE_NAME/.
• W polu iat użyj sygnatury czasowej utworzenia tokena, określonej jako liczba sekund, które upłynęły od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Poczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa przypada w zbyt odległej przeszłości lub w przyszłości, serwer może zgłosić błąd.
• W polu exp użyj sygnatury czasowej wygaśnięcia tokena, określonej jako liczba sekund od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Maksymalna dozwolona wartość to iat + 3600.

Podczas podpisywania tokena JWT, który ma być przekazywany do urządzenia mobilnego, pamiętaj, aby użyć konta usługi do roli sterownika lub pakietu SDK klienta. W przeciwnym razie urządzenie mobilne będzie mogło zmienić stan, z którego nie powinno mieć dostępu.

Podobnie jak w przypadku podpisywania tokena JWT, który ma być używany w wywołaniach uprzywilejowanych, użyj konta usługi z rolą superużytkownika. W przeciwnym razie operacja się nie powiedzie.

Generowanie tokena JWT na potrzeby testowania

Generowanie tokenów z terminala może być pomocne podczas testowania.

Aby można było wykonać te czynności, Twoje konto użytkownika musi mieć przypisaną rolę twórcy tokenów konta usługi:

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Utwórz nowy plik o nazwie unsigned_token.json zawierający zawartość poniżej. Właściwość iat to bieżący czas (w sekundach) po epoce, który można pobrać, uruchamiając w terminalu polecenie date +%s. Właściwość exp to czas wygaśnięcia podany 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ż godzina w przyszłości.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Następnie uruchom to polecenie gcloud, aby podpisać token w imieniu swojego konta usługi superużytkownika:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

Podpisany token JWT zakodowany w Base64 powinien być teraz przechowywany w pliku signed_token.jwt. Token jest ważny przez następną godzinę.

Teraz możesz przetestować token, uruchamiając polecenie curl w punkcie końcowym wyświetlania listy pojazdów REST:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

Pojazdy i ich cykl życia

Pojazd to element reprezentujący parę kierowcy i pojazd. Obecnie nie można osobno śledzić kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawy tworzy pojazd za pomocą identyfikatora dostawcy (musi być taki sam jak identyfikator projektu w projekcie Google Cloud zawierającym konto usługi używane do wywoływania interfejsów API Fleet Engine), a także identyfikatora pojazdu należącego do dostawcy przejazdu lub dostawcy usług dostawy.

Pojazd, który nie został zaktualizowany za pomocą UpdateVehicle w ciągu 7 dni, zostanie automatycznie usunięty. Wywołanie funkcji CreateVehicle z użyciem już istniejącej pary identyfikatora dostawcy/identyfikatora pojazdu to błąd. W przypadku pojazdów, które nie są często aktualizowane, można zaradzić sobie 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ływanie funkcji CreateVehicle po zwróceniu zdarzenia UpdateVehicle z błędem NOT_FOUND.

Aktualizacje lokalizacji pojazdu

Aby uzyskać najlepszą wydajność Fleet Engine, zapewnij jej strumień aktualizacji lokalizacji pojazdów. Aby zapewnić aktualizacje, użyj jednego z tych sposobów:

1. Użyj pakietu SDK sterownika – Android, iOS – najprostsza opcja.
2. Użyj kodu niestandardowego, który jest przydatny, jeśli lokalizacje są przekazywane przez backend lub używasz urządzeń innych niż Android lub iOS.

Element Pojazd zawiera powtórzone pole TripWaypoint (RPC | REST) o nazwie waypoints(RPC | REST). To pole uwzględnia pozostałe punkty pośrednie na trasie podróży, w kolejności, w jakiej do nich dotrze. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je w miarę, jak podróże zmieniają stan. Takie punkty na drodze można rozpoznać po polu TripId i polu WaypointType.

Rozszerzenie możliwości dopasowania pojazdu

Zwykle to usługi wspólnych przejazdów lub dostawcy usług dostawy odpowiadają za dopasowywanie próśb o podróż do pojazdów. 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 być reklamowany dla wszystkich 3 grup. Gdy Fleet Engine otrzyma żądanie podróży wymagającej srebrnych możliwości, wyszukiwanie uwzględnia dany pojazd. Ten sposób korzystania z atrybutów dotyczy pojazdów o różnych możliwościach.

Atrybuty pojazdu można aktualizować na 2 sposoby. Jednym z nich jest UpdateVehicle API. Gdy używasz tego interfejsu API, cały zestaw atrybutów pojazdu jest ustawiony na tę wartość. Nie można aktualizować tylko jednego atrybutu. Drugą metodą jest interfejs API UpdateVehicleAttributes. Ta metoda wymaga tylko aktualizacji atrybutów. Atrybuty zawarte w żądaniu zostaną ustawione na nową wartość lub dodane. Nieokreślone atrybuty nie zostaną zmienione.

PORADNIK: Utwórz pojazd

Aby można było śledzić flotę, dla każdego pojazdu 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 usług wspólnych lub dostawy, Fleet Engine nie obsługuje obecnie kont usługi z wielu projektów Google Cloud, które mają dostęp do tego samego zasobu Vehicles.

Obiekt Vehicle można utworzyć w stanie OFFLINE lub ONLINE. Jeśli utworzono ONLINE, może 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.

Szczegółowe informacje 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 przez funkcję CreateVehicle jest utworzoną encją Vehicle.

Przykład

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

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

Logi Google Cloud Platform dotyczące tworzenia pojazdów

Po otrzymaniu wywołania punktu końcowego CreateVehicle interfejs Fleet Engine API zapisuje 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ć też informacje o zwróconym elemencie Vehicle.

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

---
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ć takie powiadomienia, postępuj zgodnie z instrukcjami podanymi tutaj.

WSKAZÓWKA: aktualizowanie lokalizacji pojazdu

Jeśli nie używasz pakietu Driver SDK do aktualizowania lokalizacji pojazdu, możesz wykonać bezpośrednie wywołanie do Fleet Engine z informacją 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

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

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

Podpowiedź: zaktualizuj inne pola dotyczące pojazdu

Aktualizacje innych atrybutów stanu pojazdu odbywają się rzadziej niż zmiany pozycji. Aktualizacje atrybutów innych niż last_location wymagają uprawnień superużytkownika Fleet Engine.

UpdateVehicleRequest zawiera element update_mask wskazujący, które pola zaktualizować. Sposób działania tego pola jest taki sam jak w dokumentacji Protobuf dla masek pól.

Jak wspomnieliśmy w sekcji Atrybuty pojazdu, zaktualizowanie pola attributes wymaga zapisania wszystkich atrybutów, 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.

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

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 pojazdu

Po otrzymaniu wywołania 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ć też informacje o zwróconym elemencie Vehicle.

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 dotyczących pojazdu

Gdy istniejący pojazd zostanie zaktualizowany, interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcjami 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 wysyłanie zamówień. Interfejs SearchVehicles API zwraca pozycjonowaną listę kierowców, którzy pasują do atrybutów zadań z atrybutami pojazdów należących do Twojej floty. Aby dowiedzieć się więcej, przeczytaj artykuł o wyszukiwaniu kierowców w pobliżu.

Przykład

Podczas wyszukiwania dostępnych pojazdów Fleet Engine domyślnie wyklucza pojazdy podczas aktywnych podróży. Usługi Dostawcy wspólnych przejazdów lub dostawcy usług muszą wyraźnie informować o tych usługach w żądaniach wyszukiwania. Poniższy przykład pokazuje, jak uwzględnić te pojazdy w wyszukiwaniu pojazdów pasujących do przejazdu z centrum handlowego GrandIndonesia East Mall do centrum kongresowego Balai Sidang w Dżakarcie.

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

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

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Zapytanie dotyczące filtrowania pojazdów

SearchVehicles i ListVehicles obsługują filtrowanie atrybutów pojazdu za pomocą zapytania o filtr. Składnię zapytań filtrów znajdziesz tutaj: AIP-160.

Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie atrybutów pojazdu i nie można ich używać w innych polach. Zapytanie filtra działa jak klauzula AND z innymi ograniczeniami, takimi jak minimum_capacity lub vehicle_types w SearchVehiclesRequest.

PORADNIK: Wyświetlanie listy pojazdów

Funkcja SearchVehicles została zoptymalizowana pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w kolejności rankingowej i służy głównie do znajdowania kierowców w pobliżu najlepiej pasujących do danego zadania. Czasami jednak chcesz znaleźć wszystkie pojazdy spełniające określone kryteria, nawet jeśli konieczne jest stronicowanie wyników. Do tego celu służy funkcja ListVehicles.

Interfejs ListVehicles API pozwala znaleźć wszystkie pojazdy, które spełniają określone opcje żądania. Interfejs ListVehicles API zwraca listę pojazdów w projekcie podzieloną na strony, która spełnia określone wymagania.

Aby filtrować według atrybutów pojazdu, zapoznaj się z sekcją Zapytanie dotyczące filtrowania pojazdów.

Przykład

W tym przykładzie filtrujemy pola vehicle_type i atrybuty za pomocą ciągu znaków filter.

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

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;
}

Interfejs Trip API oraz cykl życia są podobne do interfejsu Vehicle API i cykl życia. Dostawca wspólnych przejazdów odpowiada za tworzenie podróży za pomocą interfejsów Fleet Engine. Fleet Engine udostępnia zarówno usługę RPC ( TripService), jak i zasoby REST provider.trips. Interfejsy te umożliwiają tworzenie elementów Podróże, przesyłanie próśb o informacje, wyszukiwanie i aktualizowanie.

Element Trip ma pole stanu, które pozwala śledzić postępy w jego cyklu życia. Wartości są przenoszone z zakresu NEW do COMPLETE oraz CANCELED i UNKNOWN_TRIP_STATUS. Informacje o RPC znajdziesz w trip_status lub TripStatus dla REST.

• NEW
• ENROUTE_TO_PICKUP
• ARRIVED_AT_PICKUP
• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• COMPLETE

Twoja usługa może zaktualizować podróż do: CANCELED z dowolnego z tych stanów. Gdy usługa tworzy podróż, wyszukiwarka ustawia stan na NEW. Pole vehicle_id jest opcjonalne. Tak jak w przypadku pojazdów usługi te automatycznie usuwają podróże po 7 dniach bez aktualizacji. Jeśli Twoja usługa spróbuje utworzyć podróż o identyfikatorze, który już istnieje, zostanie zwrócony błąd. Podróż jest uznawana za „aktywną”, jeśli ma inny stan niż COMPLETE lub CANCELED. To rozróżnienie jest ważne w polu active_trips w elemencie Pojazd i 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 trakcie trasy, przed zmianą lub usunięciem vehicle_id stan podróży musi być ustawiony na NEW lub CANCELED.

Stan ten jest istotny przy wdrażaniu dodatkowej obsługi podróży. Ta obsługa umożliwia Dostawcy przypisanie nowej podróży do Pojazdu w trakcie aktywnej podróży. Kod tworzenia podróży powrotnej 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óżach powrotnych znajdziesz w artykule na temat tworzenia podróży obejmujących wiele punktów pośrednich.

Pozostałe punkty na drodze

Element Podróż zawiera pole powtarzane TripWaypoint (RPC | REST) o nazwie remainingWaypoints(RPC | REST). To pole obejmuje wszystkie punkty pośrednie, które pojazd musi przebyć w ustalonej kolejności, zanim będzie ostatni w danej podróży. Oblicza się na podstawie pozostałych punktów na trasie pojazdu. W przypadkach użycia „Powrotny” i „Podwożenie” ta lista zawiera punkty na trasie z innych podróży, które zostaną przebyte przed tą podróżą, ale nie uwzględnia punktów pośrednich po tej podróży. Punkt pośredni na liście ma oznaczenie TripId i WaypointType.

Zależność między stanem podróży a pozostałymi punktami pośrednimi pojazdu

Pozostałe punkty na trasie pojazdu (RPC | REST) zostaną zaktualizowane, gdy Fleet Engine otrzyma prośbę o zmianę stanu podróży. Poprzedni punkt na trasie zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, gdy stan parametru tripStatus(RPC | REST) zmieni się z innego na ENROUTE_TO_XXX. Oznacza to, że gdy stan podróży zostanie zmieniony z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru podróży będzie nadal znajdować się na liście pozostałych punktów pośrednich pojazdu, ale gdy status podróży zmieni się na ENROUTE_TO_INTERMEDIATE_DESTINATION lub ENROUTE_TO_DROPOFF, punkty odbioru pojazdu zostaną usunięte z drogi.

Tak samo jest w przypadku ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Po ARRIVED_AT_INTERMEDIATE_DESTINATION bieżący cel pośredni nie zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, dopóki pojazd nie zgłosi, że kieruje on do następnego punktu pośredniego.

Gdy stan podróży zostanie zmieniony na COMPLETED, żadne punkty pośrednie z tej podróży nie pojawią się na liście pozostałych punktów pośrednich pojazdu.

PORADNIK: tworzenie podróży

Aby każde żądanie podróży było śledzone i dopasowywane do pojazdów floty, należy utworzyć encję Trip. Aby utworzyć podróż, użyj punktu końcowego CreateTrip z elementem CreateTripRequest.

Do utworzenia podróży wymagane są te atrybuty:

• parent – ciąg znaków zawierający identyfikator dostawcy utworzony podczas tworzenia projektu Google Cloud.
• trip_id – ciąg znaków utworzony przez dostawcę usług wspólnych przejazdów.
• trip – kontener z podstawowymi metadanymi opisującymi podróż.
  • trip_type – liczba wskazująca, czy w podróży mogą uczestniczyć inni pasażerowie z innego miejsca wylotu i celu podróży w tym samym pojeździe (SHARED) czy tylko z jedną osobą (EXCLUSIVE).
  • pickup_point – TerminalLocation reprezentujący punkt początkowy podróży. Więcej informacji znajdziesz w dokumentacji RPC lub dokumentacji REST.

Podczas tworzenia podróży możesz podać te informacje:number_of_passengers, dropoff_point i vehicle_id. Chociaż te pola nie są wymagane, jeśli je podasz, zostaną zachowane. Pozostałe pola Podróże są ignorowane. Na przykład wszystkie podróże zaczynają się od trip_status o wartości NEW nawet wtedy, gdy w prośbie o utworzenie podasz trip_status z CANCELED.

Przykład

Poniższy przykład tworzy wycieczkę do Grand Indonesia East Mall. Podróż jest przeznaczona dla 2 pasażerów. Pole provider_id obiektu Trip musi być takie samo jak identyfikator projektu. W tym przykładzie dostawca usług 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, może ona wywołać UpdateTrip i zmienić vehicle_id, gdy podróż zostanie przypisana do pojazdu.

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

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 na potrzeby tworzenia podróży

Po otrzymaniu wywołania punktu końcowego CreateTrip interfejs Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu CreateTrip. Jeśli wywołanie się powiedzie, będzie zawierać też informacje o zwracanym obiekcie Trip.

WSKAZÓWKA: aktualizowanie informacji o podróży

Element Trip zawiera pola, które umożliwiają śledzenie przez usługę i raportowanie postępów w podróży za pomocą pakietu Driver SDK i SDK dla konsumentów. Aby zaktualizować właściwości, użyj komunikatu UpdateTripRequest. Spowoduje to zaktualizowanie pól Podróż zgodnie z field_mask żądania. Zapoznaj się z sekcją UpdateTripRequest.

Dostawca wspólnych przejazdów jest odpowiedzialny za aktualizowanie tych atrybutów:

• Informacje o podróży.
• Identyfikator pojazdu. w momencie jego utworzenia lub po dopasowaniu pojazdu do podróży.
• zmiany dotyczące miejsca odbioru, miejsca wysyłania lub punktów pośrednich;

Gdy korzystasz z funkcji udostępniania trasy za pomocą pakietu Driver SDK lub Consumer SDK, Fleet Engine automatycznie aktualizuje te pola:

• Trasy
• Szacowany czas dotarcia
• Pozostała odległość
• Lokalizacja pojazdu
• Pozostałe punkty na trasie

Zobacz instrukcje Tripw RPC lub Resource.Trip w REST.

Logi Google Cloud Platform dotyczące aktualizacji podróży

Po otrzymaniu wywołania punktu końcowego UpdateTrip interfejs Fleet Engine API zapisuje wpis logu za pomocą 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 zwracanym obiekcie Trip.

PORADNIK: Wyszukiwanie podróży

Fleet Engine obsługuje wyszukiwanie podróży. Jak wspomnieliśmy wcześniej, podróż jest automatycznie usuwana po 7 dniach, więc SearchTrips nie udostępnia pełnej historii wszystkich Podróży.

SearchTrips to elastyczny interfejs API, ale na liście poniżej uwzględniono 2 przypadki użycia.

• Określanie aktywnych podróży pojazdem – dostawca może określić aktywne trasy pojazdu. W SearchTripsRequest właściwość vehicle_id jest ustawiona na rozważany pojazd, a active_trips_only – na true.

• Uzgadnianie dostawcy i stanu Fleet Engine – dostawca może użyć parametru SearchTrips, aby upewnić się, że jego stan podróży jest zgodny ze stanem Fleet Engine. Jest to szczególnie ważne w przypadku TripStatus. Jeśli stan podróży przypisanej do Pojazdu jest nieprawidłowo ustawiony na COMPLETE lub CANCELED, SearchVehicles nie uwzględnia pojazdu.

Aby użyć funkcji SearchTrips w ten sposób, pozostaw pole vehicle_id puste, ustaw w polu active_trips_only wartość true i w polu minimum_staleness ustaw czas dłuższy niż w większości przypadków podróży. Możesz np. użyć godziny. Wyniki obejmują Podróże, które nie są UKOŃCZONE ani ANULOWANE i nie zostały zaktualizowane w ciągu ponad godziny. Dostawca powinien sprawdzić te podróże, aby upewnić się, że ich stan we Fleet Engine jest prawidłowo zaktualizowany.

Rozwiązywanie problemów

W przypadku błędu DEADLINE_EXCEEDED stan Fleet Engine jest nieznany. Dostawca powinien ponownie wywołać funkcję CreateTrip, która zwróci kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednia prośba została spełniona przed DEADLINE_EXCEEDED. Więcej informacji o postępowaniu z błędami w podróży znajdziesz w przewodnikach po interfejsie Consumer API: Android lub iOS.

Pomoc w podwożeniu

Do pojazdu obsługującego TripType.SHARED możesz przypisać kilka podróży SHARED. Musisz określić kolejność wszystkich nieprzeniesionych punktów pośrednich we wszystkich Podróżach przypisanych do pojazdu w ramach tej wspólnej przejazdu przez Trip.vehicle_waypoints podczas przypisywania obiektu vehicle_id do wspólnej podróży (w prośbie CreateTrip lub UpdateTrip). Zapoznaj się z opisem vehicle_waypoints o RPC lub vehicleWaypoints w przypadku REST.

Obsługa wielu miejsc docelowych

Określ pośredni punkt docelowy

Pole intermediateDestinations i intermediateDestinationIndex w podróży (RPC | REST) trzeba połączyć, by wskazać miejsce docelowe.

Aktualizacja pośredniego miejsca docelowego

Miejsca docelowe pośrednich możesz zaktualizować w narzędziu UpdateTrip. Podczas aktualizowania miejsc docelowych pośrednich musisz podać pełną listę pośrednich miejsc docelowych, w tym tych, które były już odwiedzane, a nie tylko te nowo dodane lub do zmodyfikowania. Gdy intermediateDestinationIndex wskazuje indeks po pozycji nowo dodanego/zmodyfikowanego pośredniego miejsca docelowego, nowe/zaktualizowane pośrednie miejsce docelowe nie zostanie dodane do pozycji waypoints pojazdu ani remainingWaypoints podróży. Dzieje się tak, ponieważ wszystkie miejsca docelowe pośrednie przed intermediateDestinationIndex są traktowane jako już odwiedzone.

Zmiany stanu podróży

Pole intermediateDestinationsVersion w (RPC | REST) jest wymagane w żądaniu aktualizacji stanu podróży wysyłanym do Fleet Engine, aby wskazać, że wystąpił błąd pośredniego miejsca docelowego. 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 środek pośredni, pojazd przemieści się w następnej kolejności. Gdy tripStatus to ARRIVED_AT_INTERMEDIATE_DESTINATION, liczba z zakresu [0..N-1] wskazuje, gdzie znajduje się pojazd.

Przykład

Poniższy przykładowy kod pokazuje, jak zaktualizować stan podróży tak, aby doprowadził do pierwszego miejsca docelowego pośredniego, przy założeniu, że masz utworzoną podróż obejmującą wiele miejsc docelowych i minęła ona miejsce odbioru.

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;
}

Fleet Engine API używa Google Cloud Pub/Sub do publikowania powiadomień na ten temat utworzonych przez konsumenta Google Cloud Project. Usługa Pub/Sub nie jest domyślnie włączona dla Fleet Engine w Twoim projekcie Google Cloud. Aby włączyć Pub/Sub, prześlij zgłoszenie do zespołu pomocy lub skontaktuj się z inżynierem ds. obsługi klienta.

Aby utworzyć temat w projekcie Cloud, wykonaj te instrukcje. Identyfikator tematu musi mieć wartość „fleet_engine_notifications”.

Temat musi zostać utworzony w tym samym projekcie Cloud, który wywołuje interfejsy Fleet Engine API.

Po utworzeniu tematu musisz przyznać interfejsowi Fleet Engine API uprawnienia do publikowania w tym temacie. Aby to zrobić, kliknij utworzony przed chwilą temat i dodaj nowe uprawnienie. Aby otworzyć edytor uprawnień, konieczne może być kliknięcie POKAŻ PANEL INFORMACYJNY. Podmiotem zabezpieczeń powinien być geo-fleet-engine@system.gserviceaccount.com, a rola to Pub/Sub publisher.

Aby skonfigurować projekt Cloud pod kątem subskrybowania 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 PubMessage kluczem data_format, a 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

• Pojazd
• FieldMask

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"
    }
  }
}