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 Podróże i Postępy zamówień. Obsługuje transakcje między pakietem SDK sterownika, pakietem SDK dla konsumentów i usługą backendu, które mogą komunikować się z Fleet Engine za pomocą wywołań gRPC lub REST.

Wymagania wstępne

Na potrzeby programowania pamiętaj, aby zainstalować pakiet SDK Cloud (gcloud) i uwierzytelnić się w projekcie.

powłoka

gcloud auth login

Powinien pojawić się komunikat o powodzeniu, taki jak:

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

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

powłoka

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

Jeśli to polecenie powoduje błąd, skontaktuj się z administratorem projektu i przedstawicielem zespołu pomocy Google, aby uzyskać dostęp.

Logowanie

Fleet Engine może zapisywać komunikaty dotyczące odbieranych wywołań interfejsu API w logach platformy Google Cloud. Informacje o tym, jak odczytywać i analizować logi, znajdziesz w dokumentacji Cloud Logging.

W projektach utworzonych przed 10 lutego 2022 r. logowanie może nie być domyślnie włączone. Więcej informacji znajdziesz w dokumentacji dotyczącej logowania.

Biblioteki klienta

Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te biblioteki ułatwiają pracę programistom w porównaniu z nieprzetworzonym REST lub gRPC. Instrukcje uzyskiwania bibliotek klienta dla aplikacji serwera znajdziesz w artykule Biblioteki klienta.

W przykładach w języku Java w tej dokumentacji założono, że znasz gRPC.

Uwierzytelnianie i autoryzacja

Możliwości związane z podróżą i postępem 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. W 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żą one do tworzenia tokenów sieciowych JSON, które przyznają różne zestawy uprawnień w zależności od ról. Aby zmniejszyć ryzyko nadużyć, możesz utworzyć wiele kont usługi o minimalnym zestawie wymaganych ról.

Postęp podróży i zamówienia ma następujące role:

RolaOpis
Użytkownik pakietu SDK konsumenta Fleet Engine

roles/fleetengine.consumerSdkUser		 Daje uprawnienie do wyszukiwania pojazdów oraz pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi o tej roli są zwykle używane z urządzeń mobilnych w aplikacji do wspólnych przejazdów lub dostawy.
Użytkownik pakietu SDK Fleet Engine Driver SDK

roles/fleetengine.driverSdkUser		 Daje uprawnienie do aktualizowania lokalizacji pojazdów i tras oraz do pobierania informacji o pojazdach i podróżach. Tokeny utworzone przez konto usługi o tej roli są zwykle używane na urządzeniach mobilnych w aplikacji do wspólnych przejazdów lub dostawcy.
Superużytkownik usługi Fleet Engine

roles/fleetengine.serviceSuperUser		 Przyznaje uprawnienia wszystkim interfejsom API pojazdów i podróży. Tokeny utworzone przez konto usługi z tą rolą są zwykle używane z serwerów backendu.

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

Na tych standardowych rolach opierają się pakiety SDK sterowników i konsumenta.

Możesz też utworzyć role niestandardowe, które pozwalają łączyć ze sobą dowolny zestaw uprawnień. Pakiety SDK sterowników i konsumenta wyświetlają komunikaty o błędach, gdy brakuje wymaganego uprawnienia. Dlatego zdecydowanie zalecamy, aby nie korzystać ze standardowego zestawu ról, ale nie z nich niestandardowych.

Jeśli chcesz tworzyć tokeny JWT dla niezaufanych klientów, dodanie użytkowników do roli twórcy tokenów konta usługi umożliwia im tworzenie tokenów za pomocą narzędzi wiersza poleceń gcloud.

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

Gdzie my-user@example.com to adres e-mail używany do uwierzytelniania w gcloud (gcloud auth list --format='value(account)').

Biblioteka uwierzytelniania Fleet Engine

Fleet Engine używa tokenów sieciowych JSON (JWT) do ograniczania dostępu do interfejsów API Fleet Engine. Nowa biblioteka uwierzytelniania Fleet Engine dostępna na GitHubie upraszcza tworzenie tokenów JWT Fleet Engine i bezpieczne ich podpisy.

Biblioteka zapewnia te korzyści:

  • Upraszcza proces tworzenia tokenów Fleet Engine.
  • Udostępnia mechanizmy podpisywania tokenów inne niż pliki danych logowania (np. podszywanie się pod konto usługi).
  • Dołącza podpisane tokeny do żądań wychodzących, które pochodzą z odcinka gRPC lub klienta GAPIC.

Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji

Jeśli nie korzystasz z biblioteki uwierzytelniania Fleet Engine, tokeny internetowe JSON (JWT) musisz utworzyć bezpośrednio w bazie kodu. Musisz więc dogłębnie znać tokeny JWT i ich związek z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.

Tokeny internetowe JSON (JWT) w Fleet Engine zapewniają krótkotrwałe uwierzytelnianie i zapewniają, ż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 roszczenia zawiera takie informacje jak czas utworzenia tokena, czas życia tokenów, usługi, do których zgłoszono prawa dostępu, i inne informacje o autoryzacji umożliwiające określenie zakresu dostępu, np. identyfikator pojazdu.

Sekcja nagłówka JWT zawiera te pola:

PoleOpis
alg Algorytm, którego chcesz użyć. „RS256”.
typ Typ tokena. „JWT”.
dziecko Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` w pliku JSON konta usługi. Pamiętaj, aby użyć klucza z konta usługi z odpowiednim poziomem uprawnień.

Sekcja deklaracji JWT zawiera te pola:

PoleOpis
iss Adres e-mail Twojego konta usługi.
zast. Adres e-mail Twojego konta usługi.
jst Usługa SERVICE_NAME Twojego konta usługi, w tym przypadku https://fleetengine.googleapis.com/
IAT Sygnatura czasowa utworzenia tokena podana w sekundach, które upłynęły od 00:00:00 czasu UTC 1 stycznia 1970 r. Odczekaj 10 minut, aby się zniekształcić. Jeśli sygnatura czasowa przypada w zbyt odległej przeszłości lub w przyszłości, serwer może zgłosić błąd.
exp Sygnatura czasowa wygaśnięcia tokena podana w sekundach, które upłynęły od 1 stycznia 1970 r. o godz. 00:00:00 czasu UTC. Żądanie nie powiedzie się, jeśli sygnatura czasowa przypada za więcej niż godzinę.
autoryzacja W zależności od przypadku użycia może zawierać parametr „vehicleid” lub „tripid”.

Tworzenie 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 deklarację w sekcji autoryzacji, gdzie klucz vehicleid lub tripid jest ustawiony 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 odbywa się w podróży, czy w pojeździe. Backend Fleet Engine zapewnia, że pojazd jest powiązany z żądaną podróżą przed wprowadzeniem modyfikacji.

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

Dostawca wspólnych przejazdów lub dostawy powinien użyć atrybutu vehicleid lub tripid ze znakiem „*”, aby dopasować wszystkie pojazdy i Podróże. Pamiętaj, że token JWT może zawierać oba tokeny, nawet jeśli nie jest to wymagane. Upraszcza to implementację podpisywania tokenów.

Przypadki użycia JWT

Poniżej znajdziesz 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 sterownika:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}
  • W polu kid w nagłówku podaj identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu private_key_id pliku JSON konta usługi.
  • W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email pliku JSON konta usługi.
  • W polu aud podaj https://SERVICE_NAME/.
  • W polu iat użyj sygnatury czasowej utworzenia tokena określonej jako sekundy, które upłynęły od 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut, aby się zniekształcić. Jeśli sygnatura czasowa jest w zbyt odległej przeszłości lub przypada 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 sekundy od godziny 00:00:00 czasu UTC, 1 stycznia 1970 roku. Maksymalna dozwolona wartość to iat + 3600.

Podczas podpisywania tokena JWT, który ma zostać przekazany na urządzenie mobilne, użyj konta usługi do roli sterownika lub pakietu SDK klienta. W przeciwnym razie urządzenie mobilne będzie miało możliwość zmiany stanu.

Podobnie, jeśli podpisujesz token JWT, który ma być używany na potrzeby wywołań uprzywilejowanych, użyj konta usługi z rolą superużytkownika. W przeciwnym razie operacja się nie powiedzie.

Tworzenie tokena JWT na potrzeby testowania

Podczas testowania może być pomocne generowanie tokenów z terminala.

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 epoce. Można go wyszukać, uruchamiając w terminalu date +%s. Właściwość exp to czas wygaśnięcia wyrażony w sekundach po epoce, który można obliczyć, dodając wartość 3600 do wartości iat. Czas wygaśnięcia nie może być dłuższy niż 1 godzina w przyszłości.

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

Następnie uruchom to polecenie gcloud, aby podpisać token w imieniu 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ę.

Możesz teraz przetestować token, uruchamiając polecenie curl w punkcie końcowym Wyświetlenie 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-pojazd. Obecnie nie można osobno śledzić kierowcy i pojazdu. Dostawca wspólnych przejazdów lub dostawy tworzy pojazd za pomocą identyfikatora dostawcy (który musi być taki sam jak identyfikator projektu Google Cloud zawierającego konto usługi używane do wywoływania interfejsów Fleet Engine API) oraz identyfikatora pojazdu należącego do dostawcy usług wspólnych lub dostawy.

Pojazd, który w ciągu 7 dni nie został zaktualizowany w aplikacji UpdateVehicle, zostanie automatycznie usunięty. Wystąpił błąd podczas wywoływania funkcji CreateVehicle z użyciem istniejącej pary identyfikator dostawcy/identyfikator pojazdu. W przypadku pojazdów, które nie są często aktualizowane, można załatwić takie sprawy na 2 sposoby: często wywołując CreateVehicle oczekiwaną parę identyfikatora dostawcy/identyfikatora pojazdu i odrzucając błąd, jeśli pojazd już istnieje, lub wywoływanie CreateVehicle po wystąpieniuUpdateVehicle zwrócenia błędu NOT_FOUND.

Aktualizacje lokalizacji pojazdu

Aby uzyskać najlepszą wydajność Fleet Engine, zapewnij jej strumień aktualizacji lokalizacji pojazdów. Aktualizacje możesz przesłać na jeden z tych sposobów:

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

Rodzaj pojazdu

Element „Pojazd” zawiera wymagane pole VehicleType, które zawiera wyliczenie Category, które można określić jako AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE lub PEDESTRIAN. Typ pojazdu może służyć jako kryteria filtrowania w SearchVehicles i ListVehicles.

W przypadku wszystkich tras dla pojazdów używana jest odpowiednia wartość RouteTravelMode, jeśli kategoria jest ustawiona na AUTO, TWO_WHEELER, BICYCLE lub PEDESTRIAN. Jeśli kategoria jest ustawiona na TAXI lub TRUCK, routing jest traktowany tak samo jak tryb AUTO.

Atrybuty pojazdu

Element Pojazd zawiera pole powtarzane VehicleAttribute. Te atrybuty nie są interpretowane przez Fleet Engine. Interfejs SearchVehicles API zawiera pole, które wymaga, aby dopasowane Vehicles musi zawierać wszystkie uwzględnione atrybuty ustawione na określoną wartość.

Pamiętaj, że pole atrybutu jest uzupełnieniem kilku innych obsługiwanych pól w komunikacie Vehicle, takich jak vehicle_type i supported_trip_types.

Pozostałe punkty na drodze dla pojazdów

Element Vehicle zawiera pole powtarzane TripWaypoint (RPC | REST) o nazwie waypoints(RPC | REST). To pole zawiera pozostałe punkty na trasie w kolejności, w jakiej do nich dotrze. Fleet Engine oblicza to pole, gdy podróże są przypisywane do pojazdu, i aktualizuje je wraz ze zmianą stanu podróży. Takie punkty na trasie można rozpoznać po polach TripId i WaypointType.

Rozszerzanie możliwości dopasowania pojazdu

Zwykle za dopasowywanie żądań przejazdu do pojazdów odpowiada firma świadcząca usługi w zakresie przejazdów lub dostawy. Usługa może korzystać z atrybutów pojazdu, aby uwzględnić pojazd w większej liczbie wyszukiwań. Na przykład usługodawca 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 spełniać wszystkie 3 warunki. Gdy Fleet Engine otrzyma prośbę o podróż, która wymaga srebrnych możliwości, wyszukiwanie uwzględnia ten pojazd. Ten sposób korzystania z atrybutów obejmuje pojazdy o różnych możliwościach.

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

PORADNIK: Utwórz pojazd

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

Użyj punktu końcowego CreateVehicle z CreateVehicleRequest do utworzenia pojazdu.

Element provider_id obiektu Vehicle musi być identyfikatorem projektu (np. mój projekt na żądanie) projektu Google Cloud zawierającego konta usługi, które będą używane do wywołania Fleet Engine. Pamiętaj, że chociaż wiele kont usługi może korzystać z Fleet Engine dla tego samego dostawcy usług udostępniania lub przejazdów, 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.

Element Vehicle można utworzyć w stanie OFFLINE lub ONLINE. Jeśli zostanie utworzony ONLINE, może zostać natychmiast zwrócony w odpowiedzi na SearchVehicles zapytań.

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.

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

Wartość zwrócona z metody CreateVehicle to utworzona encja Vehicle.

Przykład

powłoka

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Zobacz dokumentację dotyczącą providers.vehicles.create.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

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

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

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

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

Logi Google Cloud Platform dotyczące tworzenia pojazdów

Po otrzymaniu wywołania punktu końcowego CreateVehicle interfejs Fleet Engine API zapisuje w logach platformy Google Cloud wpis logu. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym Vehicle.

powłoka

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

Powinien zostać wydrukowany rekord podobny do tego:

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

Powiadomienia Cloud Pub/Sub dotyczące tworzenia pojazdów

Po utworzeniu nowego pojazdu interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcjami opisanymi tutaj.

Podpowiedź: zaktualizuj lokalizację pojazdu

Jeśli nie zaktualizujesz lokalizacji pojazdu za pomocą pakietu Driver SDK, możesz wykonać bezpośrednie wywołanie do Fleet Engine i podać lokalizację pojazdu. W przypadku każdego aktywnego pojazdu Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę i nie częściej niż co 5 sekund. Te aktualizacje wymagają tylko uprawnień użytkownika pakietu Fleet Engine Driver SDK.

Przykład

powłoka

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

Zobacz dokumentację providers.vehicles.update.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

Podpowiedź: zaktualizuj inne pola dotyczące pojazdów

Aktualizacje innych atrybutów stanu pojazdu występują rzadziej niż aktualizacje pozycji. Aktualizacje atrybutów innych niż last_location wymagają uprawnień superużytkownika Fleet Engine.

UpdateVehicleRequest zawiera element update_mask wskazujący, które pola mają zostać zaktualizowane. Sposób działania 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, które zostaną zachowane. Nie można po prostu zaktualizować wartości jednej pary klucz-wartość w wywołaniu UpdateVehicle. Do aktualizowania wartości określonych atrybutów można użyć interfejsu API UpdateVehicleAttributes.

Przykład

Ten przykład włącza funkcję back_to_back.

powłoka

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

Zobacz dokumentację providers.vehicles.update.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

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

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

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

Logi Google Cloud Platform na potrzeby aktualizacji pojazdu

Po otrzymaniu wywołania punktu końcowego UpdateVehicle interfejs Fleet Engine API zapisuje w logach platformy Google Cloud wpis logu. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym Vehicle.

powłoka

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

Powiadomienia Cloud Pub/Sub o aktualizacjach pojazdu

Gdy istniejący pojazd zostanie zaktualizowany, interfejs Fleet Engine API publikuje w Cloud Pub/Sub powiadomienie. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcjami opisanymi tutaj.

PORADNIK: Wyszukiwanie pojazdów

Fleet Engine obsługuje wyszukiwanie pojazdów. Interfejs SearchVehicles API pozwala znajdować w pobliżu kierowców, którzy najlepiej sprawdzą się w takich zadaniach jak obsługa przejazdów czy zamówienia dostawy. Interfejs SearchVehicles API zwraca ranking kierowców pasujących do atrybutów zadań i atrybutów pojazdów w Twojej flocie. 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 aktywne. Usługi dostawców usług wspólnych przejazdów lub dostawy muszą być wyraźnie uwzględnione w żądaniach wyszukiwania. Z przykładu poniżej dowiesz się, jak uwzględnić te pojazdy w wyszukiwaniu pojazdów pasujących do podróży z centrum handlowego GrandIndonesia East Mall do centrum kongresowego Balai Sidang w Dżakarcie.

powłoka

Najpierw zaktualizuj lokalizację pojazdu, który utworzyliśmy w poprzednich krokach, aby się kwalifikował. W świecie rzeczywistym robi to w pojeździe pakietu SDK Driver SDK na urządzeniu z Androidem lub iOS.

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

Po przeprowadzeniu wyszukiwania powinien być co najmniej ten pojazd.

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

Zobacz dokumentację providers.vehicles.search.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

Zapytanie dotyczące filtrowania pojazdów

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

Pamiętaj, że zapytania filtra obsługują TYLKO filtrowanie według 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

Narzędzie SearchVehicles zostało zoptymalizowane pod kątem szybkiego znajdowania niewielkiej liczby pojazdów w rankingu i głównie do znajdowania kierowców w pobliżu najlepiej pasujących do konkretnego zadania. Czasami jednak chcesz znaleźć wszystkie pojazdy, które spełniają określone kryteria, nawet jeśli konieczne jest stronicowanie wyników. Typ ListVehicles został opracowany z myślą o tym przypadku.

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

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

Przykład

W tym przykładzie filtrujemy pola vehicle_type i atrybuty przy użyciu ciągu znaków filter.

powłoka

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

Zobacz dokumentację providers.vehicles.list.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

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

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Podróże i ich cykl życia

Interfejs Trip API i cykl życia są podobne do interfejsu Vehicle API i cyklu życia. Dostawca wspólnych przejazdów 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. Umożliwiają one tworzenie obiektów Trip, wysyłanie żądań informacji, wyszukiwanie oraz aktualizowanie treści.

Element Trip ma pole stanu, które pozwala śledzić jego postęp w całym cyklu życia. Wartości są przenoszone z NEW do COMPLETE plus CANCELED i UNKNOWN_TRIP_STATUS. Zapoznaj się z informacjami o trip_status RPC i Stanie Trip 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 jej stan na NEW. Wartość vehicle_id jest opcjonalna. Tak jak w przypadku pojazdów, usługi usuwają podróże automatycznie po 7 dniach bez aktualizacji. Jeśli Twoja usługa spróbuje utworzyć podróż o identyfikatorze, który już istnieje, zostanie zwrócony błąd. Podróż jest uznawana za „aktywną”, jeśli ma inny stan niż COMPLETE lub CANCELED. To rozróżnienie jest ważne w polu active_trips w elemencie Pojazd i w polu SearchTripsRequest.

Usługa może zmienić vehicle_id przypisany do podróży tylko wtedy, gdy stan to NEW lub CANCELED. Jeśli Kierowca anuluje podróż, gdy jest w drodze, stan Podróży musi być ustawiony na NEW lub CANCELED, zanim vehicle_id zostanie zmieniony lub usunięty.

Stan jest ważny przy wdrażaniu dodatkowej obsługi podróży. Ta obsługa umożliwia Dostawcy przypisanie nowej podróży do Pojazdu, gdy jest on w aktywnej podróży. Kod do utworzenia podróży po kolei jest taki sam jak w przypadku pojedynczej podróży i korzysta z tego samego identyfikatora pojazdu. Fleet Engine dodaje miejsce początkowe i cel nowej podróży do punktów na trasie pojazdu. Więcej informacji o podróży po kolei znajdziesz w artykule Tworzenie podróży obejmujących wiele punktów pośrednich.

Pozostałe punkty na trasie

Element Trip zawiera pole powtarzane TripWaypoint (RPC | REST) o nazwie remainingWaypoints(RPC | REST). To pole zawiera wszystkie punkty pośrednie, którymi pojazd musi podróżować w kolejności, zanim będzie ostatni punkt docelowy w tej podróży. Oblicza je na podstawie pozostałych punktów na trasie pojazdu. W przypadku korzystania z podróży wstecz i podwożenia ta lista zawiera punkty na trasie z innych podróży, które zostaną przebyte przed tą podróżą, ale nie zawiera punktów pośrednich po niej. Punkt pośredni na liście można rozpoznać po elementach TripId i WaypointType.

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

Pozostałe punkty drogi 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 status podróży zmieni się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru będzie nadal widoczny 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, punkt odbioru zostanie usunięty.

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

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

PORADNIK: Utwórz podróż

Aby każde żądanie podróży było śledzone i dopasowywane do pojazdów we flocie, 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 znaków zawierający identyfikator dostawcy utworzony podczas tworzenia projektu Google Cloud.
  • trip_id – ciąg tekstowy utworzony przez dostawcę wspólnych przejazdów.
  • trip – kontener z podstawowymi metadanymi opisującymi podróż.
    • trip_type – liczba wskazująca, czy w podróży mogą uczestniczyć tylko pasażerowie z innego miejsca wylotu i celu podróży w tym samym pojeździe (SHARED) lub tylko w ramach tej podróży (EXCLUSIVE).
    • pickup_point – TerminalLocation wskazują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 żądaniu utworzenia prześlesz trip_status o wartości CANCELED.

Przykład

Poniższy przykład tworzy wycieczkę do Grand Indonesia East Mall. Podróż jest przeznaczona dla 2 pasażerów i jest przeznaczona tylko dla 2 pasażerów. Wartość provider_id elementu Trip musi być taka sama jak identyfikator projektu. W tym przykładzie dostawca wspólnych przejazdów utworzył projekt Google Cloud project-id. Ten projekt musi mieć konta usługi używane do wywoływania Fleet Engine. Stan podróży to NEW.

Później, gdy usługa dopasuje podróż do pojazdu, usługa może wywołać UpdateTrip i zmienić vehicle_id, gdy podróż zostanie przypisana do pojazdu.

powłoka

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

Zobacz dokumentację dotyczącą providers.trips.create.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Logi Google Cloud Platform na potrzeby tworzenia podróży

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

Podpowiedź: zaktualizuj informacje o podróży

Element Trip zawiera pola umożliwiające śledzenie przez usługę oraz raportowanie postępów w podróży przez pakiet SDK sterownika i pakiet 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. Zobacz UpdateTripRequest.

Dostawca wspólnych przejazdów odpowiada za aktualizowanie tych atrybutów:

  • Stan podróży.
  • Identyfikator pojazdu. W momencie tworzenia pojazdu lub po dopasowaniu pojazdu do podróży.
  • Zmiany dotyczące punktu odbioru, miejsca docelowego lub punktów pośrednich.

Podczas korzystania 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

Skorzystaj z instrukcji Tripw RPC lub Resource.Trip w REST.

Logi Google Cloud Platform na potrzeby aktualizacji podróży

Po otrzymaniu wywołania punktu końcowego UpdateTrip interfejs Fleet Engine API zapisuje wpis logu przy użyciu logów platformy Google Cloud. Wpis logu zawiera informacje o wartościach w żądaniu UpdateTrip. Jeśli wywołanie się powiedzie, będzie zawierać informacje o zwróconym Trip.

PORADNIK: Wyszukiwanie podróży

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

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

  • Określanie aktywnych podróży pojazdu – Dostawca może określić aktywne podróże 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ć SearchTrips, aby upewnić się, że stan podróży jest taki sam jak stan Fleet Engine. Jest to szczególnie ważne w przypadku obiektu TripStatus. Jeśli stan podróży przypisany do Pojazdu nie jest prawidłowo ustawiony na COMPLETE lub CANCELED, SearchVehicles nie uwzględnia tego pojazdu.

Aby użyć elementu SearchTrips w ten sposób, pozostaw pole vehicle_id puste, ustaw active_trips_only na true i ustaw wartość minimum_staleness na czas dłuższy niż większość czasu trwania podróży. Możesz użyć np. godziny. Wyniki obejmują podróże, które nie są UKOŃCZONE ani ANULOWANE i które nie zostały zaktualizowane w ciągu 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 zwraca kod 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednia prośba została zrealizowana przed DEADLINE_EXCEEDED. Więcej informacji o obsłudze błędów w podróżach znajdziesz w przewodnikach po interfejsie Consumer API na Androidzie i iOS.

Obsługa przejazdów Carpool

Do pojazdu obsługującego TripType.SHARED możesz przypisać kilka podróży typu SHARED. Musisz określić kolejność wszystkich nieprzekazanych punktów pośrednich we wszystkich podróżach przypisanych do pojazdu w ramach tej wspólnej przejazdu za pomocą Trip.vehicle_waypoints, gdy przypisujesz element vehicle_id do podróży współdzielonej (w żądaniu CreateTrip lub UpdateTrip). Zapoznaj się z informacjami na temat vehicle_waypoints dla RPC i vehicleWaypoints dla REST.

Obsługa wielu miejsc docelowych

Wskaż pośrednie miejsce docelowe

Pola intermediateDestinations i intermediateDestinationIndex w podróży (RPC | REST) zostaną połączone, aby wskazać miejsce docelowe.

Zaktualizuj pośrednie miejsce docelowe

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

Zmiany stanu podróży

Pole intermediateDestinationsVersion w (RPC | REST) jest wymagane w żądaniu aktualizacji stanu podróży wysyłanym do Fleet Engine, aby wskazać, że miejsce docelowe pośrednie zakończyło się powodzeniem. Docelowy pośredni punkt docelowy jest określony w polu intermediateDestinationIndex. Gdy tripStatus (RPC | REST) ma wartość ENROUTE_TO_INTERMEDIATE_DESTINATION, liczba z zakresu od [0..N-1] wskazuje, przez który pośredni punkt docelowy pojazd przejedziesz pojazdem. 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, aby dotrzeć do pierwszego miejsca docelowego pośredniego, przy założeniu, że masz utworzoną podróż obejmującą wiele miejsc docelowych i minęła już jej punkt odbioru.

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

PORADNIK: subskrybowanie powiadomień z interfejsu Fleet Engine API

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

Aby utworzyć temat 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.

Jeśli chcesz skonfigurować projekt Cloud pod kątem subskrypcji powiadomień, wykonaj te instrukcje

Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych formatach danych: protobuf i json. Format danych każdego powiadomienia jest oznaczony w atrybutach PubsubMessage kluczem data_format i wartością protobuf lub json.

Schemat powiadomień:

Protobuf

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}