Rozwiązanie na żądanie dotyczące przejazdów i dostaw jest obecnie dostępne tylko dla wybranych partnerów.

Ta strona została przetłumaczona przez Cloud Translation API.

Pierwsze kroki z Fleet Engine

Interfejs Fleet Engine On-demand Rides and Deliveries API umożliwia zarządzanie podróżami i stan pojazdu dla aplikacji dotyczących podróży i postępu realizacji zamówień. Obsługuje transakcje między pakietem Driver SDK, pakietem Consumer SDK usługa backendu, która może komunikować się z Fleet Engine przez gRPC lub REST.

Wymagania wstępne

Na potrzeby programowania musisz zainstalować Cloud przez pakiet SDK (gcloud) i są uwierzytelnieni w do swojego projektu.

powłoka

gcloud auth login

Powinien wyświetlić się komunikat o powodzeniu, taki jak:

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

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

powłoka

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

Jeśli to polecenie spowoduje błąd, skontaktuj się z administratorem projektu i z przedstawicielem zespołu pomocy Google.

Logowanie

Flota Engine może zapisywać komunikaty logu dotyczące odbieranych wywołań interfejsu API w logach Google Cloud Platform. Zapoznaj się z dokumentacją Cloud Logging, aby dowiedzieć się więcej Omówienie sposobu odczytywania i analizowania logów.

Logowanie może być domyślnie wyłączone w przypadku projektów utworzonych przed 10 lutego 2022 r. Zobacz dokumentacja logowania .

Biblioteki klienta

Publikujemy biblioteki klienta w kilku popularnych językach programowania. Te pomogą zwiększyć wygodę programistów w porównaniu do nieprzetworzonych plików REST czy gRPC. Aby uzyskać instrukcje dotyczące uzyskiwania bibliotek klienta dla aplikacji serwerowej, zobacz Biblioteki klienta.

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

Uwierzytelnianie i autoryzacja

Możesz skonfigurować funkcje zapewniane przez opcję Podróż i Postęp realizacji zamówienia w konsoli Google Cloud. Te interfejsy API i pakiety SDK wymagają użycia tokenów sieciowych JSON, zostały podpisane przy użyciu kont usługi utworzonych z Konsola Cloud.

Konfigurowanie projektu Cloud

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

Aby utworzyć projekt Google Cloud:

Utwórz projekt Google Cloud za pomocą konsoli Google Cloud.
W panelu interfejsów API i usług włącz Interfejs API Local Rides i Deliveries.

Konta usługi są powiązane z co najmniej 1 rolą. Służą do tworzenia Tokeny internetowe JSON, które przyznają różne zestawy uprawnień w zależności od role. Aby zmniejszyć ryzyko nadużyć, zazwyczaj można utworzyć wiele kont usługi, każde z minimalnym wymaganym zestawem ról.

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

Rola	Opis
Użytkownik pakietu konsumenckiego pakietu SDK Fleet Engine `roles/fleetengine.consumerSdkUser`	Przyznaje uprawnienia do wyszukiwania pojazdów i pobierania informacji na temat pojazdów i podróży. Tokeny utworzone przez konto usługi z tym identyfikatorem są zwykle używane podczas wspólnych przejazdów lub do dostawy produktów na urządzeniach mobilnych.
Użytkownik pakietu SDK Fleet Engine Driver `roles/fleetengine.driverSdkUser`	Przyznaje uprawnienia do aktualizowania lokalizacji i tras pojazdów w celu pobierania informacji o pojazdach i podróżach. Utworzone tokeny przez konto usługi z tą rolą są zwykle używane z wspólnych przejazdów czy aplikacji kierowców na urządzeniach mobilnych.
Administrator Fleet Engine na żądanie `roles/fleetengine.ondemandAdmin`	Przyznaje uprawnienia do odczytu i zapisu wszystkich zasobów pojazdu i podróży. Podmioty zabezpieczeń z tą rolą nie muszą używać tokenów JWT – zamiast tego powinny użyć domyślnego uwierzytelniania aplikacji. Niestandardowe żądania JWT są ignorowane. Ta rola powinna być ograniczona do zaufanych środowisk (backendu klienta).
~~Superużytkownik usługi FleetEngine~~ (WYCOFANY) `roles/fleetengine.serviceSuperUser`	Przyznaje uprawnienia do wszystkich interfejsów API związanych z pojazdami i podróżami. Wygenerowane tokeny przez konto usługi z tą rolą są zwykle używane z backendu serwerów. Ta rola została wycofana. Preferowane `roles/fleetengine.ondemandAdmin`.

Na przykład utwórz konto usługi dla każdej z 3 ról i przypisz swoją rolę.

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

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

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

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

Możesz też utworzyć role niestandardowe, które pozwolą Ci dowolnego zestawu uprawnień, które można połączyć w pakiet. Pakiety SDK sterowników i klientów indywidualnych będą wyświetlać komunikaty o błędach za każdym razem, brakuje wymaganych uprawnień. Dlatego zdecydowanie zalecamy używając standardowego zestawu ról przedstawionych powyżej, a nie ról niestandardowych.

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

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

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

Biblioteka uwierzytelniania Fleet Engine

Fleet Engine używa tokenów sieciowych JSON (JWT), aby ograniczyć dostęp do Interfejsy Fleet Engine API. Nowa biblioteka uwierzytelniania Fleet Engine dostępne na GitHubie, upraszcza tworzenie tokenów JWT Fleet Engine i bezpieczne ich podpisywanie.

Biblioteka zapewnia te korzyści:

Upraszcza proces tworzenia tokenów Fleet Engine.
Zapewnia mechanizmy podpisywania tokenami inne niż pliki danych logowania (np. podszywa się pod konto usługi).
Dołącza podpisane tokeny do żądań wychodzących wysyłanych z atrapy gRPC lub klient GAPIC.

Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji

Jeśli nie używasz biblioteki uwierzytelniania Fleet Engine, tokeny internetowe JSON (JWT) muszą być utworzone bezpośrednio w bazie kodu. Aby to zrobić, musisz mieć Omówienie tokenów JWT i ich związku z Fleet Engine. Dlatego Zdecydowanie zalecamy skorzystanie z biblioteki uwierzytelniania Fleet Engine.

Tokeny internetowe JSON (JWT) we Fleet Engine zapewniają uwierzytelnianie krótkotrwałe oraz zapewnić, że urządzenia mogą modyfikować wyłącznie pojazdy, podróże i zadania w celach do których ma upoważnienie. Tokeny JWT zawierają nagłówek i sekcję deklaracji. Sekcja nagłówka zawiera takie informacje jak: klucz prywatny do użycia (uzyskany z kont usługi) i szyfrowanie algorytmem bezpieczeństwa. Sekcja dotycząca roszczeń zawiera takie informacje jak: czas utworzenia tokena, czas życia tokenów, usługi zgłaszania praw do informacji o dostępie i innych informacji dotyczących upoważnienia w zakresie ograniczonym dostęp; np. identyfikator pojazdu.

Sekcja nagłówka JWT zawiera te pola:

Pole	Opis
Alg	Algorytm, który ma być używany. „RS256”.
typ	Typ tokena. JWT.
dziecko	Identyfikator klucza prywatnego konta usługi. Tę wartość znajdziesz w polu `private_key_id` pliku JSON konta usługi. Pamiętaj, aby użyć klucza z konta usługi o odpowiednim poziomie uprawnień.

Sekcja deklaracji JWT zawiera te pola:

Pole	Opis
Iss	Adres e-mail konta usługi.
zast.	Adres e-mail konta usługi.
Aud	Twoje konto usługi to SERVICE_NAME, w tym przypadku https://fleetengine.googleapis.com/
Iat	Sygnatura czasowa określająca, kiedy token został utworzony, wyrażony w sekundach. od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa w przeszłości lub w przyszłości, serwer może zgłosić błąd.
eksperyment	Sygnatura czasowa wygaśnięcia tokenu podana w sekundach od godz. 00:00:00 czasu UTC, 1 stycznia 1970 r. Żądanie nie powiedzie się, jeśli sygnatura czasowa to za więcej niż godzinę.
autoryzacja	W zależności od przypadku użycia może zawierać parametr „vehicleid” lub „tripid”.

Utworzenie tokena JWT oznacza jego podpisanie. Instrukcje i przykłady kodu dotyczące tworzenia i podpisywania tokena JWT znajdziesz tutaj Autoryzacja konta usługi bez protokołu OAuth. Następnie możesz dołączyć podpisany token do wywołań gRPC lub innych używanych metod aby uzyskać dostęp do Fleet Engine.

Żądania JWT

Podczas tworzenia ładunku JWT dodaj dodatkową deklarację w autoryzacji z kluczem vehicleid lub tripid ustawionym na wartość klucza identyfikator pojazdu lub identyfikator podróży, którego dotyczy połączenie.

Pakiet Driver SDK zawsze używa twierdzenia vehicleid, niezależnie od tego, czy działa podróż lub pojazd. Backend Fleet Engine zapewnia, że pojazd jest powiązana z żądaną podróżą przed wprowadzeniem zmiany.

Pakiet SDK klienta zawsze używa roszczenia tripid.

Dostawca wspólnych przejazdów lub dostawca usług dostawy powinien użyć karty vehicleid lub tripid ze znakiem „*” do pasują do wszystkich kategorii Pojazdy i Podróże. Pamiętaj, że token JWT może zawierać oba tokeny: nawet jeśli nie jest wymagana, może to uprościć implementację podpisywania tokenów.

Przypadki użycia JWT

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

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

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

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

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

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

W polu kid w nagłówku podaj klucz prywatny konta usługi ID. Tę wartość znajdziesz w polu private_key_id swojej usługi plik JSON konta.
W polach iss i sub podaj adres e-mail konta usługi. Tę wartość znajdziesz w polu client_email na koncie usługi Plik JSON.
W polu aud wpisz https://SERVICE_NAME/.
W polu iat użyj sygnatury czasowej utworzenia tokena, określony jako czas, który upłynął od godziny 00:00:00 czasu UTC, 1 stycznia 1970 r. Odczekaj 10 minut na zniekształcenie. Jeśli sygnatura czasowa jest zbyt odległa w przeszłości, lub w przyszłości serwer może zgłosić błąd.
W polu exp użyj sygnatury czasowej, gdy token wygaśnie, określona jako sekundy od 00:00:00 czasu UTC, 1 stycznia 1970 r. Maksymalna wartość dozwolona wartość to iat + 3600.

Podczas podpisywania tokena JWT, który ma być przekazany na urządzenie mobilne, użyj funkcji konto usługi z rolą Driver lub Consumer SDK. W przeciwnym razie funkcja będzie mieć możliwość zmiany stanu, którego nie powinna mieć.

Podobnie podczas podpisywania tokena JWT, który ma być używany w wywołaniach z podwyższonymi uprawnieniami, upewnij się też, aby używać konta usługi z rolą superużytkownika. W przeciwnym razie nie powiedzie się.

Generowanie tokena JWT na potrzeby testowania

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

Aby wykonać te czynności, użytkownik konto musi mieć przypisaną rolę twórcy tokenów konta usługi:

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

Utwórz nowy plik o nazwie unsigned_token.json z poniższą zawartością. iat jest wartością bieżącą czasu w sekundach po epoce. Może ona być pobrane przez uruchomienie w terminalu date +%s. Właściwość exp to czas wygaśnięcia w sekundach po epoce, który można obliczyć za pomocą Dodaję 3600 do iat. Czas wygaśnięcia nie może przekraczać godziny w w przyszłości.

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

Następnie uruchom to polecenie gcloud, aby podpisać token w imieniu zespołu Super Konto usługi użytkownika:

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

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

Możesz teraz przetestować token, uruchamiając polecenie curl dla listy pojazdów Punkt końcowy REST:

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

Pojazdy i ich cykl życia

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

Pojazd, który nie został zaktualizowany przez UpdateVehicle po 7 dniach, zostanie automatycznie usunięta, a przypisane do niej podróże, jeśli są, zostaną oznaczone jako nieprzypisane. Zalecane metody utrzymania dostępności pojazdu we Fleet Engine jest regularne aktualizowanie swojej lokalizacji. Aktualizacje do większości innych pól w elemencie Vehicle też przedłuży swoją żywotność, pod warunkiem że wartość nowego pola jest inna niż wartość w dotychczasowym polu;

UWAGA: niektóre pola w elemencie Vehicle, np. device_settings, mają charakter czysto debugowany. informacje, które nie są utrwalone przez Fleet Engine. Nie spowoduje to ich aktualizacji przedłużyć żywotność elementu Vehicle.

Podczas wywoływania funkcji CreateVehicle przy użyciu: Para identyfikatora dostawcy i identyfikatora pojazdu, która już istnieje. Sprawa samochodów, które nie są często aktualizowane. Można sobie z nimi radzić na 2 sposoby: często dzwoniący CreateVehicle z oczekiwanym identyfikatorem dostawcy/identyfikatorem pojazdu i odrzuceniem błąd, jeśli pojazd już istnieje; lub dzwoniąc pod numer CreateVehicle po UpdateVehicle zwraca błąd NOT_FOUND.

Aktualizacje lokalizacji pojazdu

Aby uzyskać najlepszą wydajność we Fleet Engine, zapewnij jej strumień pojazdów aktualizacje lokalizacji. Zaktualizuj informacje na jeden z tych sposobów:

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

Rodzaj pojazdu

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

Wszystkie trasy dla pojazdów będą używać odpowiedniej wartości RouteTravelMode, jeśli kategoria jest ustawiona na AUTO, TWO_WHEELER, BICYCLE lub PEDESTRIAN. Jeśli kategoria jest ustawiona na TAXI lub TRUCK, routing jest traktowany tak samo jak tryb AUTO.

Atrybuty pojazdu

Element Pojazd zawiera powtarzane pole VehicleAttribute. Te nie będą interpretowane przez Fleet Engine. SearchVehicles Interfejs API zawiera pole, które wymaga, aby pasował Vehicles musi zawierać wszystkie zawarte atrybuty ustawione na określoną wartość.

Pamiętaj, że pole atrybutu zostało dodane do kilku innych obsługiwanych pól. w wiadomości Vehicle, na przykład vehicle_type i supported_trip_types.

Pozostałe punkty na trasie pojazdu

Element Pojazd zawiera powtarzalne pole TripWaypoint (RPC | REST), o nazwie waypoints(RPC | REST). To pole zawiera pozostałe punkty na trasie podróży w kolejności pojazd dotrze do nich. Fleet Engine oblicza to pole, gdy podróże przypisany do pojazdu i aktualizuje go w miarę zmiany stanu podróży. Te punkty pośrednie można zidentyfikować za pomocą pól TripId i WaypointType.

Zwiększanie możliwości dopasowania pojazdu

Zwykle za dopasowanie odpowiadają zwykle usługi wspólnych przejazdów lub firm kurierskich dla pojazdów. Usługa może wykorzystać atrybuty pojazdu, aby uwzględnić podczas większej liczby wyszukiwań. Dostawca może na przykład zaimplementować zestaw atrybutów odpowiadających poziomom bonusów lub możliwości oferowanych przez pojazdem. Na przykład trzy poziomy mogą być zbiorem atrybutów z wartościami logicznymi wartości: is_bronze_level, is_silver_level i is_gold_level. Pojazd mogą kwalifikować się do wszystkich 3 elementów. Gdy Fleet Engine otrzyma żądanie w podróży wymagającej zaawansowanych umiejętności, wyszukiwanie obejmuje również dany pojazd. Użycie atrybutów w ten sposób obejmuje pojazdy oferowane w rozmaitych usługach funkcje zabezpieczeń.

Atrybuty pojazdu można aktualizować na 2 sposoby. Jeden to UpdateVehicle API. Podczas korzystania z tego interfejsu API cały zestaw atrybutów pojazdu jest ustaw wartość. Nie można zaktualizować tylko jednego atrybutu. Drugą metodą jest interfejs API UpdateVehicleAttributes. Ta metoda zajmuje tylko atrybuty do zaktualizowania. Atrybuty zawarte w żądaniu zostaną ustawiona na nową wartość lub dodaną wartość; nieokreślone atrybuty nie zostaną zmienione.

INSTRUKCJA: tworzenie pojazdu

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

Użyj punktu końcowego CreateVehicle z elementem CreateVehicleRequest, aby utworzyć Pojazd.

Element provider_id elementu Vehicle musi być identyfikatorem projektu (np. mój projekt na żądanie) projektu Google Cloud, który zawiera Konta usługi, które będą używane do wywoływania Fleet Engine. Pamiętaj, że choć wiele kont usługi może uzyskiwać dostęp do Fleet Engine na potrzeby tego samego wspólnych przejazdów lub dostawcą usług dostarczania, Fleet Engine nie obsługuje obecnie kont usługi wiele projektów Google Cloud uzyskujących dostęp do tego samego obiektu Vehicles.

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

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

Szczegółowe informacje o pojeździe znajdziesz w sekcji Typy pojazdów. type (Typ konwersji).

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

Wartość zwrócona z metody CreateVehicle to utworzony element Vehicle.

Przykład

powłoka

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

Zobacz providers.vehicles.create odwołania.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

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

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

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

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

Logi Google Cloud Platform dotyczące tworzenia pojazdu

Interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud, gdy Odebrane wywołanie punktu końcowego CreateVehicle. Wpis logu zawiera informacje o wartościach w żądaniu CreateVehicle. Jeśli połączenie będzie zawierać również informacje o Vehicle, które zostały użyte .

powłoka

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

Powinien zostać wydrukowany rekord podobny do tego:

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

Powiadomienia Cloud Pub/Sub dotyczące tworzenia pojazdu

Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub, gdy nowy pojazdem. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcje znajdziesz tutaj.

INSTRUKCJA: aktualizowanie lokalizacji pojazdu

Jeśli nie używasz pakietu Driver SDK do aktualizowania lokalizacji pojazdu, możesz bezpośrednie połączenie z lokalizacją pojazdu we Fleet Engine. W przypadku każdego aktywnego pojazdu: Fleet Engine oczekuje aktualizacji lokalizacji co najmniej raz na minutę i nie częściej niż co 5 sekund. Te aktualizacje wymagają tylko użytkownika pakietu SDK Fleet Engine Driver uprawnień.

Przykład

powłoka

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

Zobacz providers.vehicles.update odwołania.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

INSTRUKCJA: aktualizowanie innych pól dotyczących pojazdu

Aktualizacje innych atrybutów stanu pojazdu pojawiają się rzadziej niż aktualizacje pozycji. Wymagane są aktualizacje atrybutów innych niż last_location Uprawnienia superużytkownika Fleet Engine.

Pole UpdateVehicleRequest zawiera element update_mask wskazujący, które pola . Działanie tego pola jest takie samo jak w dokumentacji Protobuf dla maski pól.

Zgodnie z opisem w atrybutach pojazdu aktualizacja Pole attributes wymaga zapisania wszystkich atrybutów w celu zachowania. it nie można zaktualizować tylko wartości jednej pary klucz-wartość w funkcji UpdateVehicle połączenie. Aby zaktualizować wartości określonych atrybutów, para klucz-wartość Można użyć interfejsu API UpdateVehicleAttributes.

Przykład

W tym przykładzie włączona jest funkcja back_to_back.

powłoka

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

Zobacz providers.vehicles.update odwołania.

Java

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

Logi Google Cloud Platform dotyczące aktualizacji pojazdów

Interfejs Fleet Engine API zapisuje wpis logu w logach platformy Google Cloud, gdy Odebrane wywołanie punktu końcowego UpdateVehicle. Wpis logu zawiera informacje o wartościach w żądaniu UpdateVehicle. Jeśli połączenie będzie zawierać również informacje o Vehicle, które zostały użyte .

powłoka

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

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

Interfejs Fleet Engine API publikuje powiadomienie przez Cloud Pub/Sub, gdy pojazd jest zaktualizowany. Aby otrzymywać takie powiadomienia, postępuj zgodnie z instrukcje znajdziesz tutaj.

INSTRUKCJA: wyszukiwanie pojazdów

Fleet Engine obsługuje wyszukiwanie pojazdów. SearchVehicles Interfejs API umożliwia znajdowanie kierowców w pobliżu, którzy najlepiej pasują do danego zadania, np. usługi przewozu osób lub prośby o dostawę. Interfejs SearchVehicles API zwraca błąd rankingowa lista kierowców pasujących do atrybutów zadań i atrybutów pojazdów w Twoją flotę. Więcej informacji: Znajdowanie kierowców w pobliżu

Przykład

Podczas wyszukiwania dostępnych pojazdów Fleet Engine wyklucza pojazdy domyślnie aktywne podróże. Usługi dostawcy wspólnych przejazdów lub dostawy muszą: bezpośrednio uwzględniać je w żądaniach wyszukiwania. Ten przykład pokazuje, jak uwzględnia te pojazdy w wyszukiwaniu pojazdów pasujących do trasy podróży Indonesia East Mall do centrum kongresowego Balai Sidang Jakarta.

powłoka

Najpierw zaktualizuj lokalizację pojazdu, którą utworzyliśmy w poprzednich krokach, jest odpowiednia. W prawdziwym świecie robiłby to aktywny pakiet Driver SDK. na urządzeniu z Androidem lub iOS w pojeździe.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Wyszukiwanie powinno zwrócić przynajmniej ten pojazd.

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

Zobacz providers.vehicles.search odwołania.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

Zapytanie dotyczące filtrowania pojazdów

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

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

INSTRUKCJA: wyświetlanie listy pojazdów

Witryna SearchVehicles jest zoptymalizowana pod kątem znajdowania niewielkiej liczby pojazdów w rankingu zamawiaj bardzo szybko. Służy głównie do znajdowania kierowców w okolicy, którzy najlepiej pasują któreś z zadań. Czasami jednak chcesz znaleźć wszystkie pojazdy spełniające określone , nawet jeśli konieczne jest stronicowanie wyników. ListVehicles to stworzonych z myślą o tych zastosowaniach.

Interfejs API ListVehicles umożliwia znalezienie wszystkich pojazdów, które spełniają określone opcje żądania. Interfejs API ListVehicles zwraca podzieloną na strony listę pojazdów w: który spełnia określone wymagania.

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

Przykład

W tym przykładzie filtrujemy: vehicle_type i atrybuty za pomocą Ciąg tekstowy filter.

powłoka

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

Zobacz providers.vehicles.list odwołania.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

Podróże i ich cykl życia

Interfejs Trip API i cykl życia są podobne do interfejsu Vehicle API i cyklu życia. Dostawca wspólnych przejazdów odpowiada za tworzenie podróży za pomocą Fleet Engine i interfejsów. Fleet Engine zapewnia zarówno usługę RPC, TripService i zasoby REST, provider.trips , Te interfejsy umożliwiają tworzenie elementu Podróże, wysyłanie żądań informacji, wyszukiwanie funkcji i aktualizacji.

Element Trip ma pole stanu, które umożliwia śledzenie postępów w cyklu życia. Wartości zmieniają się z NEW na COMPLETE plus CANCELED i UNKNOWN_TRIP_STATUS , Informacje o RPCznajdziesz w artykule trip_status lub TripStatus w przypadku REST.

NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE

Twoja usługa może zaktualizować podróż do: CANCELED z dowolnego z tych stanów. Gdy usługa utworzy podróż, wyszukiwarka ustawia jej stan na NEW. O Pole vehicle_id jest opcjonalne. Tak jak w przypadku pojazdów, nieprzypisane przejazdy są usuwane automatycznie. po 7 dniach bez aktualizacji. Jeśli Twoja usługa próbuje utworzyć podróż z który już istnieje, zwracany jest błąd. Podróż jest uznawana za „aktywną”, jeśli ma stan inny niż COMPLETE lub CANCELED. To rozróżnienie jest ważne w polu active_trips w elemencie Pojazd oraz SearchTripsRequest.

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

Stan jest ważny przy wdrażaniu jeden po drugim z pomocą w podróży. Ta pomoc umożliwia Usługodawcy przypisanie nowej trasy do pojazdu podczas gdy Pojazd jest w trakcie aktywnej podróży. Kod do utworzenia jednej podróży w drugą stronę jest taka sama jak w przypadku pojedynczej podróży identyfikatora pojazdu. Fleet Engine dodaje miejsce wylotu i cel podróży do punktów na trasie. Więcej informacji o kolejnych podróżach znajdziesz na stronie Tworzenie podróży wielopunktowych.

Pozostałe punkty na trasie

Element Trip zawiera powtarzane pole TripWaypoint (RPC | REST), o nazwie remainingWaypoints(RPC | REST). To pole obejmuje wszystkie punkty na trasie, które musi przebyć pojazd w zależności przed ostatecznym punktem wylotu. Sposób obliczania: Pozostałe punkty na trasie pojazdu. W przypadkach użycia „Powrot do siebie” i „Podwożenie” ta lista zawiera punkty pośrednie od inne przejazdy, które zostaną rozliczone przed tą podróżą, z wyłączeniem wszystkich punktów pośrednich po podróży. Punkt pośredni na liście można rozpoznać po elemencie TripId i WaypointType.

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

Pozostałe punkty pośrednie pojazdu (RPC | REST) będą zostanie zaktualizowana, gdy Fleet Engine otrzyma prośbę o zmianę stanu podróży. poprzedni punkt pośredni zostanie usunięty z listy pozostałych punktów pośrednich pojazdu, gdy tripStatus(RPC | REST) zmienił się z innego stanu na ENROUTE_TO_XXX. Oznacza to, że gdy stan podróży zmienia się z ENROUTE_TO_PICKUP na ARRIVED_AT_PICKUP, punkt odbioru nadal będzie na liście punktów pośrednich pojazdu, ale podczas podróży stan został zmieniony na ENROUTE_TO_INTERMEDIATE_DESTINATION lub ENROUTE_TO_DROPOFF, jego punkt odbioru zostanie usunięty z pozostałych punktów na trasie pojazdu.

To samo dotyczy ARRIVED_AT_INTERMEDIATE_DESTINATION i ENROUTE_TO_INTERMDEDIATE_DESTINATION. Gdy ARRIVED_AT_INTERMEDIATE_DESTINATION, Obecne pośrednie miejsce docelowe nie zostanie usunięte z pozostałej części pojazdu listę punktów pośrednich, dopóki pojazd nie zgłosi, że kieruje się do następnego punktu.

Po zmianie stanu podróży na COMPLETED żadne punkty pośrednie z tej podróży nie zostaną uwzględnione na pozostałej liście punktów pośrednich pojazdu.

INSTRUKCJA: tworzenie podróży

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

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

parent – ciąg tekstowy zawierający identyfikator dostawcy utworzony, gdy Google Projekt Cloud został utworzony.
trip_id – ciąg znaków utworzony przez dostawcę wspólnych przejazdów.
trip – kontener z podstawowymi metadanymi opisującymi podróż.
- trip_type – wyliczenie określające, czy w podróży mogą brać udział inni pasażerowie. z innego miejsca wylotu i miejsca docelowego w tym samym pojeździe (SHARED) lub tylko przez jedną stronę (EXCLUSIVE).
- pickup_point – TerminalLocation reprezentujący punkt początkowy dla podróży. Zapoznaj się z dokumentacją RPC. lub dokumentacja REST

Podczas tworzenia podróży możesz podać te dane: number_of_passengers, dropoff_point i vehicle_id. Chociaż te pola nie są wymagane, jeśli je podasz, są zachowywane. Wszystkie pozostałe pola Podróż są ignorowane. Na przykład: wszystkie podróże zacznij od trip_status o wartości NEW, nawet jeśli zdasz trip_status CANCELED w prośbie o utworzenie.

Przykład

W poniższym przykładzie jest tworzona podróż do centrum handlowego Grand Indonesia East Mall. Podróż jest przeznaczony dla 2 pasażerów i ma charakter wyłączny. Wartość provider_id właściwości Trip musi być taki sam jak identyfikator projektu. W tym przykładzie dostawca wspólnych przejazdów utworzył Projekt Google Cloud, project-id. Ten projekt musi mieć Konta usługi używane do wywoływania Fleet Engine. Stan podróży to NEW.

Później, po dopasowaniu usługi do pojazdu, usługa może nawiązać połączenie UpdateTrip i zmień vehicle_id, gdy podróż jest przypisana do pojazdu.

powłoka

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

Zobacz providers.trips.create odwołania.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

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

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

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

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

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

Interfejs Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud, gdy Odebrane wywołanie punktu końcowego CreateTrip. Wpis logu zawiera informacje o wartościach w żądaniu CreateTrip. Jeśli połączenie będzie zawierać również informacje o zwróconym obiekcie Trip.

WSKAZÓWKA: aktualizowanie podróży

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

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

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

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

Trasy
Szacowany czas zakończenia
Pozostały dystans
Lokalizacja pojazdu
Pozostałe punkty pośrednie

Zapoznaj się z informacjami Tripw RPC lub Resource.Trip w formacie REST.

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

Interfejs Fleet Engine API zapisuje wpis logu za pomocą logów platformy Google Cloud, gdy Odebrane wywołanie punktu końcowego UpdateTrip. Wpis logu zawiera informacje o wartościach w żądaniu UpdateTrip. Jeśli wywołanie się powiedzie, będzie też zawierać informacje o zwróconym obiekcie Trip.

INSTRUKCJA: wyszukiwanie wycieczek

Fleet Engine obsługuje wyszukiwanie podróży. Jak już wspomniano, Podróż jest są automatycznie usuwane po 7 dniach, więc SearchTrips nie: wyświetlić pełną historię wszystkich Podróży.

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

Określanie aktywnych podróży pojazdu – Dostawca może określić obecnie aktywne podróże pojazdu. W SearchTripsRequest makro vehicle_id jest ustawiony na rozważany pojazd i active_trips_only powinna mieć wartość true.
Uzgadnianie stanu dostawcy i floty floty – Dostawca może wykorzystać SearchTrips, aby sprawdzić, czy stan ich podróży jest taki sam jak stan floty w Fleet Engine. Jest to szczególnie ważne w przypadku aplikacji TripStatus. Jeśli stan podróży został przypisany na Pojazd nie jest prawidłowo ustawiony na COMPLETE lub CANCELED, Pojazd nie obejmuje: SearchVehicles.

Aby użyć metody SearchTrips w ten sposób, pozostaw pole vehicle_id puste, ustaw active_trips_only na true i ustaw minimum_staleness na czas dłuższy niż większość czasu trwania podróży. Możesz na przykład wybrać 1 godzinę. Wyniki obejmują Podróże, które nie są ZAKOŃCZONE ani ANULOWANE, a nie zostały zaktualizowane od ponad godziny. Dostawca powinien sprawdzić te podróże, aby upewnić się, że ich status we Fleet Engine zostały poprawnie zaktualizowane.

Rozwiązywanie problemów

W przypadku błędu DEADLINE_EXCEEDED stan Fleet Engine to nieznane. Dostawca powinien ponownie wywołać metodę CreateTrip, która zwróci błąd 201 (CREATED) lub 409 (CONFLICT). W tym drugim przypadku poprzednie żądanie zostało uznane za uzasadnione. przed DEADLINE_EXCEEDED. Więcej informacji znajdziesz w przewodnikach dotyczących interfejsu Consumer API o postępowaniu w przypadku błędów podróży: Android lub iOS.

Obsługa podwożenia w podróży

Możesz przypisać kilka przejazdów typu SHARED do pojazdu, który obsługuje usługę TripType.SHARED. Musisz określić kolejność wszystkich nieprzebytych punktów pośrednich dla wszystkich podróży przypisanych do pojazdem w tej wspólnej przejażdżce przez: Trip.vehicle_waypoints, gdy przypiszesz vehicle_id za udostępnioną podróż (w żądaniu CreateTrip lub UpdateTrip). Informacje o RPCznajdziesz w artykule vehicle_waypoints lub vehicleWaypoints w przypadku formatu REST.

Obsługa wielu miejsc docelowych

Określ średniozaawansowane miejsce docelowe

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

Zaktualizuj pośrednie miejsce docelowe

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

Zmiany stanu podróży

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

Przykład

Ten przykładowy kod ilustruje, jak zaktualizować stan podróży, aby w trasie do pierwszego pośredniego miejsca docelowego, zakładając, że utworzysz w przypadku podróży z wieloma miejscami docelowymi, a punkt odbioru minął.

Java

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

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

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

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

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

INSTRUKCJA: subskrybowanie powiadomień z interfejsu Fleet Engine API

Fleet Engine API korzysta z Google Cloud Pub/Sub do publikowania powiadomień na temat stworzony przez klienta Google Cloud Projekt. Usługa Pub/Sub nie jest domyślnie włączona dla Fleet Engine w Twojej usłudze Google Cloud w projektach AI. Aby włączyć Pub/Sub, prześlij zgłoszenie do zespołu pomocy lub skontaktuj się z inżynierem ds. obsługi klienta.

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

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

Po utworzeniu tematu musisz przyznać interfejs Fleet Engine API do publikowania w temacie. Aby to zrobić, kliknij temat, właśnie utworzył(a) i dodaje nowe uprawnienie. Aby otworzyć edytor uprawnień, konieczne może być kliknięcie POKAŻ PANEL INFORMACYJNY. Podmiot zabezpieczeń powinien być geo-fleet-engine@system.gserviceaccount.com a rolą powinien być Pub/Sub publisher.

Aby skonfigurować projekt Cloud do subskrybowania powiadomień, wykonaj te instrukcje

Interfejs Fleet Engine API opublikuje każde powiadomienie w 2 różnych danych formaty, protobuf oraz json Format danych każdego powiadomienia jest określony w sekcji Atrybuty PubsubMessage z kluczem jako data_format i wartością protobuf lub json.

Schemat powiadomień:

Protobuf

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

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

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

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

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

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

JSON

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

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

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

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

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