Pierwsze kroki z Fleet Engine

Interfejs Fleet Engine On-demand Rides and Deliveries API umożliwia zarządzanie podróżami i stanem pojazdu w aplikacjach związanych z podróżą i postępem realizacji zamówień. Obsługuje transakcje między pakietem Driver SDK, pakietem Consumer SDK i usługą backendu, która może komunikować się z Fleet Engine za pomocą wywołań gRPC lub REST.

Wymagania wstępne

Na potrzeby programowania zainstaluj pakiet SDK Cloud (gcloud) i uwierzytelnij go 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 API usługi Fleet Engine w rozwiązaniu na żądanie dotyczące przejazdów i dostaw na żądanie są odpowiednio skonfigurowane.

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

Logowanie

Fleet Engine może zapisywać komunikaty logów dotyczące otrzymywanych wywołań interfejsu API w logach Google Cloud Platform. Aby dowiedzieć się, jak odczytywać i analizować logi, zapoznaj się z dokumentacją Cloud Logging.

Logowanie może być domyślnie wyłączone w przypadku projektów utworzonych przed 10 lutego 2022 r. Więcej informacji znajdziesz w dokumentacji dotyczącej logowania.

Biblioteki klienta

Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te biblioteki ułatwią programistom obsługę nieprzetworzonych plików REST lub gRPC. Instrukcje uzyskiwania bibliotek klienta dla aplikacji serwerowej znajdziesz w artykule Biblioteki klienta.

W przykładach w Javie w tej dokumentacji zakładamy, że znasz gRPC.

Uwierzytelnianie i autoryzacja

Możliwości zapewniane przez proces Podróży i Postęp realizacji 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 za pomocą kont usługi utworzonych w Cloud Console.

Konfigurowanie projektu Cloud

Aby skonfigurować projekt w chmurze, najpierw go utwórz, 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żna zwykle utworzyć wiele kont usługi, każde z minimalnym wymaganym zestawem ról.

Działania związane z podróżą i zamówieniem są powiązane z tymi rolami:

Możesz na przykład utworzyć konto usługi dla każdej z 3 ról i przypisać im odpowiednie role.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Pakiety sterowników i pakietów SDK dla klientów indywidualnych opierają się na tych standardowych rolach.

Możesz też utworzyć role niestandardowe, które pozwalają połączyć w grupie dowolny zestaw uprawnień. Pakiety SDK sterowników i klientów będą wyświetlać komunikaty o błędach za każdym razem, gdy brakuje wymaganych uprawnień. Dlatego zdecydowanie zalecamy korzystanie ze standardowego zestawu ról przedstawionych powyżej zamiast używania ról niestandardowych.

Jeśli musisz utworzyć tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi pozwoli im tworzyć tokeny 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 Fleet Engine API. 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ż korzystające z plików danych logowania (np. podszywanie się pod konto usługi).
• Dołącza podpisane tokeny do żądań wychodzących wysyłanych z pośrednika 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) muszą być utworzone bezpośrednio w bazie kodu. Wymaga to dogłębnej wiedzy o tokenach JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.

Tokeny internetowe JSON (JWT) we Fleet Engine zapewniają uwierzytelnianie przez krótki czas i sprawiają, że urządzenia mogą modyfikować wyłącznie pojazdy, podróże i zadania, do których są uprawnione. 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 deklaracji zawiera informacje takie jak czas utworzenia tokena, czas życia tokenów, usługi, do których uzyskał dostęp, i inne informacje dotyczące autoryzacji, np. 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 umożliwiające tworzenie i podpisywanie tokena JWT znajdziesz w artykule Autoryzacja konta usługi bez OAuth. Następnie 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 w sekcji autoryzacji dodatkową deklarację z kluczem vehicleid lub tripid ustawionym na wartość identyfikatora pojazdu lub identyfikatora podróży, którego dotyczy wywołanie.

Pakiet Driver SDK zawsze używa twierdzenia vehicleid, niezależnie od tego, czy odbywa się podczas podróży, czy w pojeździe. Backend Fleet Engine upewnia się, że pojazd jest powiązany z żądaną podróżą przed wykonaniem modyfikacji.

Pakiet SDK klienta zawsze używa roszczenia tripid.

Dostawca wspólnych przejazdów lub dostawca usług dostawy powinien użyć znaku vehicleid lub tripid ze znakiem „*”, aby wyszukać wszystkie pojazdy i podróże. Pamiętaj, że token JWT może zawierać oba tokeny, nawet jeśli nie jest wymagane, ponieważ może to uprościć implementację podpisywania tokenów.

Przypadki użycia JWT

Poniżej znajdziesz przykładowy token dla opcji Serwer dostawcy:

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

Poniżej znajdziesz przykładowy token dla aplikacji konsumenta:

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

Poniżej znajdziesz przykładowy token dla aplikacji sterownika:

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

• W polu kid w nagłówku podaj 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 wpisz https://SERVICE_NAME/.
• W polu iat użyj sygnatury czasowej utworzenia tokena określonej jako czas, który upłynął od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa 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 w sekundach od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Maksymalna dozwolona wartość to iat + 3600.

Podczas podpisywania tokena JWT, który ma być przekazany na urządzenie mobilne, w roli pakietu SDK sterownika lub pakietu SDK dla klienta użyj konta usługi. W przeciwnym razie urządzenie mobilne będzie mogło zmienić stan, w którym nie powinno.

Podobnie w przypadku podpisywania tokena JWT, który ma być używany w wywołaniach z podwyższonymi uprawnieniami, używaj 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 z poniższą zawartością. Właściwość iat to bieżący czas wyrażony w sekundach po zakończeniu epoki. Aby go pobrać, uruchom w terminalu polecenie date +%s. Właściwość exp to czas do wygaśnięcia (w sekundach) po epoki. Aby go obliczyć, dodaj do wartości iat wartość 3600. Czas wygaśnięcia nie może przekraczać godziny 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 SuperUser:

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

W pliku signed_token.jwt powinien być teraz przechowywany podpisany token JWT zakodowany w standardzie Base64. Token będzie ważny przez następną godzinę.

Możesz teraz przetestować token, uruchamiając polecenie curl w punkcie końcowym REST:

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

Pojazdy i ich cykl życia

Pojazd to podmiot reprezentujący parę kierowca–pojazd. Obecnie nie można śledzić oddzielnie kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawca usług dostawy tworzy pojazd przy użyciu identyfikatora dostawcy (musi być taki sam jak identyfikator projektu w projekcie Google Cloud, który zawiera konto usługi używane do wywoływania interfejsów Fleet Engine API) oraz identyfikatora pojazdu należącego do dostawcy wspólnych przejazdów lub dostawcy dostawy.

Pojazd, który nie został zaktualizowany przez UpdateVehicle po 7 dniach, zostanie automatycznie usunięty. Wywołanie funkcji CreateVehicle z podaniem identyfikatora dostawcy i identyfikatora pojazdu, które już istnieje, powoduje błąd. W przypadku pojazdów, które nie są często aktualizowane, można rozwiązać 2 sposoby: częste wywoływanie funkcji CreateVehicle z oczekiwaną parą identyfikatora dostawcy i identyfikatora pojazdu i odrzucanie błędu, jeśli pojazd już istnieje, lub wywołanie funkcji CreateVehicle po wystąpieniu UpdateVehicle zwraca błąd NOT_FOUND.

Aktualizacje lokalizacji pojazdu

Aby uzyskać najlepszą wydajność w usłudze Fleet Engine, udostępnij jej strumień aktualizacji lokalizacji pojazdu. Zaktualizuj informacje na jeden z tych sposobów:

1. Użyj pakietu Driver SDK – Android, iOS – najprostsza opcja.
2. Użyj kodu niestandardowego – przydaje się to, gdy lokalizacje są przekazywane przez Twój backend albo jeśli korzystasz z urządzeń innych niż Android lub iOS.

Element Pojazd zawiera powtarzane pole TripWaypoint (RPC | REST) o nazwie waypoints(RPC | REST). To pole zawiera pozostałe punkty na trasie przejazdu w kolejności, w jakiej pojazd do nich dociera. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je, gdy podróże zmieniają stan. Te punkty pośrednie można zidentyfikować za pomocą pól TripId i WaypointType.

Zwiększanie możliwości dopasowania pojazdu

Za dopasowywanie żądań podróży do pojazdów odpowiadają zwykle usługi wspólnych przejazdów lub dostawców dostaw. Usługa może wykorzystać atrybuty pojazdu, aby uwzględnić pojazd w większej liczbie wyszukiwań. Dostawca może na przykład wdrożyć zestaw atrybutów odpowiadających poziomom bonusów lub możliwości zapewnianych przez pojazd. Na przykład trzy 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 tych 3 opcji. Gdy Fleet Engine otrzyma żądanie podróży wymagającej umiejętności na poziomie srebrnym, wyszukiwanie będzie obejmować ten pojazd. Użycie atrybutów w ten sposób obejmuje pojazdy 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 ma ustawioną tę wartość. Nie można zaktualizować 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 ulegną zmianie.

INSTRUKCJA: tworzenie pojazdu

Dla każdego pojazdu, który ma być śledzony we flocie, należy utworzyć element Vehicle.

Użyj punktu końcowego CreateVehicle z CreateVehicleRequest, by utworzyć pojazd.

provider_id obiektu Vehicle musi być identyfikatorem projektu (np. my-on-demand-project) 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ług ma dostęp do platformy Fleet Engine dla tego samego dostawcy usług wspólnych lub dostawcy usług dostawy, Fleet Engine nie obsługuje obecnie kont usługi z wielu projektów Google Cloud uzyskujących dostęp do tego samego Vehicles.

Vehicle można utworzyć w stanie OFFLINE lub ONLINE. Jeśli została utworzona ONLINE, może zostać natychmiast zwrócona w odpowiedzi na zapytania SearchVehicles.

Początkowe wywołanie last_location może zostać uwzględnione w wywołaniu CreateVehicle. Chociaż jest to dozwolone, nie należy tworzyć Vehicle w stanie ONLINE bez last_location.

Szczegółowe informacje o polu typu pojazdu znajdziesz w sekcji Typy pojazdów.

Szczegółowe informacje o polu atrybutów znajdziesz w sekcji Atrybuty pojazdu.

Wartość zwrócona z metody CreateVehicle to utworzony element 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 pojazdu

Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego CreateVehicle. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie 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

Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub po utworzeniu nowego pojazdu. Aby je otrzymywać, postępuj zgodnie z instrukcjami opisanymi tutaj.

INSTRUKCJA: aktualizowanie lokalizacji pojazdu

Jeśli nie używasz pakietu Driver SDK do aktualizowania lokalizacji pojazdu, możesz nawiązać bezpośrednie wywołanie do Fleet Engine, podając lokalizację pojazdu. W przypadku każdego aktywnego pojazdu Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę, a nie częściej niż co 5 sekund. Te aktualizacje wymagają uprawnień tylko użytkowników 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.

INSTRUKCJA: aktualizowanie innych pól dotyczących pojazdu

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.

UpdateVehicleRequest zawiera pole update_mask wskazujące pola, które należy zaktualizować. Działanie tego pola jest takie samo jak w dokumentacji Protobuf dotyczącej masek pól.

Jak wspomnieliśmy w atrybutach pojazdu, aktualizacja pola attributes wymaga zapisania wszystkich atrybutów. Nie można zaktualizować wartości tylko jednej pary klucz-wartość w wywołaniu UpdateVehicle. Aby zaktualizować wartości określonych atrybutów, można użyć interfejsu API UpdateVehicleAttributes.

Przykład

W tym przykładzie włączona jest funkcja 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 pojazdów

Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego UpdateVehicle. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie 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 dotyczące aktualizacji pojazdów

Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub w przypadku aktualizacji istniejącego pojazdu. Aby je otrzymywać, postępuj zgodnie z instrukcjami opisanymi tutaj.

INSTRUKCJA: wyszukiwanie pojazdów

Fleet Engine obsługuje wyszukiwanie pojazdów. Interfejs SearchVehicles API pozwala znaleźć dostępnych kierowców w pobliżu, którzy najlepiej nadają się do takich zadań jak obsługa przewozu czy prośby o dostawę. Interfejs API SearchVehicles zwraca ranking kierowców pasujących do atrybutów zadań i atrybutów pojazdów należących do Twojej floty. Więcej informacji znajdziesz w artykule Znajdowanie kierowców w pobliżu.

Przykład

Podczas wyszukiwania dostępnych pojazdów Fleet Engine domyślnie wyklucza pojazdy podczas aktywnych podróży. Usługi dostawcy wspólnych przejazdów lub dostawy muszą być wyraźnie uwzględnione w żądaniach wyszukiwania. Poniższy przykład pokazuje, jak uwzględnić te pojazdy w wynikach wyszukiwania pojazdów pasujących do podróży 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 filtra. Informacje o składni zapytań filtra znajdziesz na stronie AIP-160.

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

INSTRUKCJA: wyświetlanie listy pojazdów

Usługa SearchVehicles jest zoptymalizowana pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w rankingu. Służy głównie do znajdowania kierowców w pobliżu, którzy najlepiej się do tego nadają. Czasami jednak chcesz znaleźć wszystkie pojazdy, które spełniają określone kryteria, nawet jeśli konieczne jest stronicowanie wyników. Usługa ListVehicles została zaprojektowana z myślą o tym zastosowaniu.

Interfejs API ListVehicles umożliwia znalezienie wszystkich pojazdów, które spełniają określone opcje żądań. Interfejs API ListVehicles zwraca podzieloną na strony listę pojazdów w projekcie, które spełniają 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 filtruje się pole 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 i cykl życia są podobne do interfejsu Vehicle API i cyklu życia. Dostawca wspólnych przejazdów odpowiada za tworzenie podróży za pomocą interfejsów Fleet Engine. Fleet Engine udostępnia zarówno usługę RPC, TripService, jak i zasoby REST provider.trips. Te interfejsy umożliwiają tworzenie elementu Podróże, wysyłanie żądań informacji, funkcje wyszukiwania i aktualizacje.

Element Trip ma pole stanu, które umożliwia śledzenie postępów w cyklu życia. Wartości zostaną przeniesione od NEW do COMPLETE plus CANCELED i UNKNOWN_TRIP_STATUS. Sprawdź trip_status dla RPC 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 utworzy podróż, wyszukiwarka ustawia jej stan na NEW. Atrybut vehicle_id jest opcjonalny. Tak jak w przypadku pojazdów, usługi usuwają przejazdy automatycznie po 7 dniach bez aktualizacji. Jeśli usługa spróbuje utworzyć podróż z identyfikatorem, który już istnieje, zostanie zwrócony błąd. Podróż jest uznawana za „aktywną”, jeśli ma stan inny niż COMPLETE lub CANCELED. To rozróżnienie jest ważne w polu active_trips w elemencie „Pojazd” i w SearchTripsRequest.

Usługa vehicle_id przypisana do podróży może zmienić tylko wtedy, gdy podróż jest aktywna. Możesz to zrobić na przykład wtedy, gdy kierowca anuluje podróż na trasie, a podróż zostanie przypisana do innego pojazdu.

Stan ten jest ważny przy wdrażaniu przebiegu podróży w jedną stronę. Ta pomoc umożliwia Dostawcy przypisanie nowej trasy do Pojazdu, który jest w trakcie aktywnej podróży. Kod do tworzenia „Podróży kolejno po sobie” jest taki sam jak w przypadku pojedynczej podróży i tego samego identyfikatora pojazdu. Fleet Engine dodaje punkt początkowy i cel nowej podróży do punktów na trasie pojazdu. Więcej informacji o kolejnych podróżach znajdziesz w artykule Tworzenie podróży wielopunktowych.

Pozostałe punkty na trasie

Element Trip zawiera powtarzane pole TripWaypoint (RPC | REST) o nazwie remainingWaypoints(RPC | REST). To pole obejmuje wszystkie punkty, które pojazd musi pokonać w ustalonej kolejności, zanim zakończy się podróż w czasie podróży. Oblicza je na podstawie pozostałych punktów na trasie pojazdu. W przypadkach użycia „Powrot do siebie” i „Podwożenie” ta lista zawiera punkty pośrednie z innych podróży, które zostaną pokonane przed tą podróżą, ale nie uwzględnia punktów pośrednich po tej podróży. Punkt pośredni na liście można rozpoznać po jego TripId i WaypointType.

Związek między stanem podróży a pozostałymi punktami na trasie pojazdu

Pozostałe punkty pośrednie pojazdu (RPC | REST) zostaną zaktualizowane, gdy Fleet Engine otrzyma żądanie zmiany stanu podróży. Poprzedni punkt pośredni zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, gdy stan tripStatus(RPC | REST) zmieni się z innego na ENROUTE_TO_XXX. Oznacza to, że gdy stan podróży zmieni się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru nadal będzie 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.

To samo dotyczy ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Przy ARRIVED_AT_INTERMEDIATE_DESTINATION obecny pośredni cel podróży nie zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, dopóki pojazd nie zgłosi, że zbliży się do następnego punktu na trasie.

Po zmianie stanu podróży na COMPLETED żadne punkty na trasie tej podróży nie będą się wyświetlać na liście pozostałych punktów pośrednich pojazdu.

INSTRUKCJA: tworzenie podróży

Aby można było śledzić każde żądanie podróży i dopasowywać je do pojazdów floty, należy utworzyć element Trip. Użyj punktu końcowego CreateTrip z CreateTripRequest, aby utworzyć podróż.

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

• parent – ciąg tekstowy zawierający identyfikator dostawcy utworzony podczas tworzenia projektu Google Cloud.
• trip_id – ciąg znaków utworzony przez dostawcę wspólnych przejazdów.
• trip – kontener z podstawowymi metadanymi opisującymi podróż.
  • trip_type – wyliczenie określające, czy w podróży mogą być inni pasażerowie z innego miejsca wylotu i z innego miejsca docelowego tym samym pojazdem (SHARED) czy tylko z jedną osobą (EXCLUSIVE).
  • pickup_point – TerminalLocation reprezentujący punkt początkowy podróży. Zobacz dokumentację RPC lub dokumentację REST.

Podczas tworzenia podróży możesz podać number_of_passengers, dropoff_point i vehicle_id. Te pola nie są wymagane, ale jeśli je podasz, zostaną zachowane. Wszystkie pozostałe pola Podróż są ignorowane. Na przykład wszystkie podróże zaczynają się od trip_status wynoszącego NEW, nawet jeśli w żądaniu utworzenia przekażesz trip_status o wartości CANCELED.

Przykład

W poniższym przykładzie jest tworzona podróż do centrum handlowego Grand Indonesia East Mall. Podróż jest przeznaczona tylko dla 2 pasażerów. provider_id elementu Trip musi być taki sam jak identyfikator projektu. W tym przykładzie dostawca wspólnych przejazdów utworzył projekt Google Cloud project-id. Ten projekt musi mieć konta usługi używane do wywoływania Fleet Engine. Stan podróży to NEW.

Później, po dopasowaniu usługi do pojazdu, usługa może wywołać metodę 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 Google Cloud Platform dotyczące tworzenia podróży

Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego CreateTrip. Wpis logu zawiera informacje o wartościach w żądaniu CreateTrip. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Trip.

WSKAZÓWKA: aktualizowanie podróży

Element Trip zawiera pola, które umożliwiają śledzenie podróży przez usługę oraz raportowanie postępów podróży przez pakiet Driver SDK i pakiet SDK dla klientów indywidualnych. Aby zaktualizować właściwości, użyj komunikatu UpdateTripRequest. Spowoduje to zaktualizowanie pól Podróży zgodnie z wartością field_mask żądania. Zobacz UpdateTripRequest.

Dostawca wspólnych przejazdów odpowiada za aktualizację tych atrybutów:

• Stan podróży.
• Identyfikator pojazdu. W momencie utworzenia lub po dopasowaniu pojazdu do trasy.
• Zmiany dotyczące odbioru, odjazdu lub punktów pośrednich.

Fleet Engine automatycznie aktualizuje te pola, gdy używasz funkcji udostępniania trasy za pomocą pakietu Driver SDK lub pakietu SDK dla klientów indywidualnych:

• Trasy
• Szacowany czas dotarcia
• Pozostały dystans
• Lokalizacja pojazdu
• Pozostałe punkty pośrednie

Sprawdź Tripw RPC lub Resource.Trip w REST.

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

Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud po otrzymaniu wywołania do punktu końcowego UpdateTrip. Wpis logu zawiera informacje o wartościach w żądaniu UpdateTrip. Jeśli wywołanie się powiedzie, pojawi się też informacja o zwróconym obiekcie Trip.

INSTRUKCJA: wyszukiwanie wycieczek

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

SearchTrips to elastyczny interfejs API, ale poniższa lista uwzględnia 2 przypadki użycia.

• Określanie aktywnych podróży pojazdu – Dostawca może określić obecnie aktywne podróże pojazdu. W SearchTripsRequest wartość vehicle_id jest ustawiona na rozważany pojazd, a active_trips_only powinna mieć wartość true.

• Uzgadnianie stanu dostawcy i floty floty – dostawca może użyć parametru SearchTrips, aby sprawdzić, czy stan ich podróży i Fleet Engine są zgodne. Jest to szczególnie ważne w przypadku aplikacji TripStatus. Jeśli stan podróży przypisanej do pojazdu nie jest prawidłowo ustawiony na COMPLETE lub CANCELED, pojazd nie jest uwzględniany przez SearchVehicles.

Aby użyć SearchTrips w ten sposób, pozostaw pole vehicle_id puste, ustaw active_trips_only na true, a minimum_staleness ustaw czas dłuższy niż większość czasu trwania podróży. Możesz na przykład wybrać 1 godzinę. Wyniki obejmują Podróże, które nie zostały UKOŃCZONE ani ANULOWANE i nie zostały zaktualizowane od ponad godziny. Dostawca powinien sprawdzić te Podróże, aby upewnić się, że ich stan 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ć metodę CreateTrip, która zwraca kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednie żądanie zostało zrealizowane przed DEADLINE_EXCEEDED. Więcej informacji o postępowaniu w przypadku błędów podróży znajdziesz w przewodnikach dotyczących interfejsu Consumer API: Android lub iOS.

Obsługa podwożenia w podróży

Możesz przypisać kilka przejazdów typu SHARED do pojazdu, który obsługuje usługę TripType.SHARED. Musisz określić kolejność wszystkich nieprzebytych punktów na trasie wszystkich podróży przypisanych do pojazdu w ramach tego wspólnego przejazdu przez Trip.vehicle_waypoints, gdy przypisujesz adres vehicle_id do wspólnej podróży (w żądaniu CreateTrip lub UpdateTrip). Sprawdź vehicle_waypoints dla RPC lub vehicleWaypoints dla REST.

Obsługa wielu miejsc docelowych

Określ średniozaawansowane miejsce docelowe

Pole intermediateDestinations i pole intermediateDestinationIndex w Trip (RPC | REST) są łączone, aby wskazać miejsce docelowe.

Zaktualizuj pośrednie miejsce docelowe

Miejsca docelowe pośrednie możesz zaktualizować w: UpdateTrip. Podczas aktualizowania pośrednich miejsc docelowych musisz podać pełną listę pośrednich miejsc docelowych łącznie z tymi, które zostały już odwiedzone, a nie tylko te nowo dodane lub zmienione. Gdy intermediateDestinationIndex wskazuje indeks po pozycji nowo dodanego/zmodyfikowanego pośredniego miejsca docelowego, nowe/zaktualizowane miejsce docelowe nie zostanie dodane do: waypoints pojazdu ani remainingWaypoints podróży. Powodem jest to, że wszystkie miejsca docelowe pośrednie przed intermediateDestinationIndex są traktowane jako już odwiedzone.

Zmiany stanu podróży

Pole intermediateDestinationsVersion w (RPC | REST) jest wymagane w żądaniu aktualizacji stanu podróży wysyłanym do Fleet Engine, aby wskazać, że pośrednie miejsce docelowe zostało już przekazane. Docelowe pośrednie miejsce docelowe określa się w polu intermediateDestinationIndex. Gdy tripStatus (RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, liczba z zakresu [0..N-1] wskazuje pośrednie miejsce docelowe, przez które pojazd będzie następny. Jeśli tripStatus to ARRIVED_AT_INTERMEDIATE_DESTINATION, liczba z zakresu od [0..N-1] wskazuje pośrednie miejsce docelowe, na którym znajduje się pojazd.

Przykład

Poniższy przykładowy kod pokazuje, jak zaktualizować stan podróży, aby wrócić do pierwszego pośredniego miejsca docelowego, przy założeniu, że została utworzona podróż obejmująca wiele miejsc docelowych i została ona zakończona.

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 temat utworzonego przez projekt Google Cloud dla klientów indywidualnych. 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 być 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 powinna mieć wartość Pub/Sub publisher.

Aby skonfigurować w projekcie Cloud subskrypcję powiadomień, postępuj zgodnie z tymi instrukcjami

Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych formatach danych: protobuf i json. Format danych każdego powiadomienia jest określony w atrybutach PubsubMessage kluczem jako data_format, a wartością jest 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"
    }
  }
}