Cerca veicoli

Nell'ambito del servizio di viaggio on demand Mobility, puoi trovare i veicoli nelle vicinanze utilizzando il metodo SearchVehicles.

Il metodo SearchVehicles ti consente di trovare i veicoli disponibili nelle vicinanze nella tua app mobile per i consumatori più adatti a una corsa o a una richiesta di consegna specifica. L'API SearchVehicles restituisce un elenco classificato di veicoli i cui attributi corrispondono agli attributi di viaggio richiesti. La classificazione è ordinata in base alla tua scelta di ETA, distanza o distanza in linea retta dal punto di prelievo.

Cerca attributi	Attributi veicolo
Località di prelievo e destinazione Tipi di veicoli e viaggi richiesti Capacità richiesta Altri attributi di corrispondenza richiesti	L'ultima posizione nota di un veicolo Lo stato, il tipo o la capacità del veicolo Altri attributi personalizzati

Utilizzare il metodo `SearchVehicles`

Per utilizzare SearchVehicles, segui questa procedura generale:

Crea un SearchVehiclesRequest in base al viaggio da assegnare.
Chiama l'API SearchVehicles (vehicleService.searchVehicles) con la richiesta creata.
Elabora il SearchVehicleResponse restituito dall'API.

Campi SearchVehiclesRequest

Utilizza i seguenti campi degli attributi obbligatori per creare un SearchVehiclesRequest:

Campo	Descrizione
parent	Obbligatorio. Deve essere nel formato providers/{provider}. Il fornitore deve essere l'ID progetto del progetto Google Cloud di cui il service account che effettua questa chiamata è membro.
vehicle_types	Obbligatorio. Tipi di veicoli richiesti: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE o PEDESTRIAN.
trip_types	Obbligatorio. EXCLUSIVE (un viaggio attivo alla volta per conducente) o SHARED (uno o più viaggi alla volta per conducente).
minimum_capacity	Obbligatorio. La capacità residua minima del veicolo per un nuovo viaggio, sia per i passeggeri sia per le consegne.
pickup_point	Obbligatorio. La località di prelievo del viaggio in coordinate di latitudine/longitudine.
dropoff_point	Facoltativo. La località di destinazione del viaggio in coordinate di latitudine/longitudine. Il campo è obbligatorio se trip_types contiene TripType.SHARED.
pickup_radius_meters	Obbligatorio. Il raggio in metri dell'area di ricerca del veicolo dal punto di prelievo.
order_by	Obbligatorio. Ordina i veicoli in base a uno dei seguenti criteri: PICKUP_POINT_ETA, l'orario di arrivo stimato del veicolo al punto di prelievo. PICKUP_POINT_DISTANCE, la distanza tra il veicolo e il punto di prelievo. DROPOFF_POINT_ETA, l'orario di arrivo stimato del veicolo per completare il viaggio al punto di arrivo. PICKUP_POINT_STRAIGHT_DISTANCE, la distanza in linea retta (non nel percorso) tra il veicolo e il punto di prelievo.
count	Obbligatorio. Il numero massimo di veicoli da restituire, da 1 a 50.
filter	Facoltativo. Una query di filtro da applicare durante la ricerca dei veicoli.
maximum_staleness	Facoltativo. Limita la ricerca solo ai veicoli che hanno inviato aggiornamenti della posizione a Fleet Engine entro la durata specificata. Se questo campo non è impostato, il server utilizza cinque minuti come valore predefinito.

Consulta la documentazione di riferimento per visualizzare l'insieme completo dei SearchVehicleRequest.

Scenari SearchVehiclesRequest

Questa sezione mostra esempi di come creare un SearchVehiclesRequest.

Supponiamo, ad esempio, che un cliente voglia essere prelevato dal ristorante X e che tu abbia quattro veicoli:

Veicolo 1: a 3500 m dal ristorante X.
Veicolo 2: a 100 m dal ristorante X con un viaggio attivo con prelievo e destinazione nelle località A e B.
Veicolo 3: a 200 m dal ristorante X con una destinazione rimanente molto lontana.
Veicolo 4: a 1000 m dal ristorante X.

Di seguito vengono visualizzate varie richieste in base al veicolo restituito.

Restituisce il veicolo 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

Restituisce i veicoli 3 e 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

Restituisce i veicoli 2, 3 e 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL

Campi SearchVehiclesResponse

Un SearchVehiclesResponse è costituito da un elenco di entità VehicleMatch, classificate in base all'attributo order_by specificato in SearchVehiclesRequest. Ogni entità VehicleMatch ha i seguenti campi:

Campo	Descrizione
vehicle	L'oggetto `Vehicle`, inclusi vehicle_id e gli attributi `Vehicle`.
vehicle_pickup_eta	L'orario di arrivo stimato del veicolo al punto di prelievo se questo viaggio venisse assegnato al veicolo in questo momento.
vehicle_pickup_distance_meter	La distanza in metri tra il veicolo e il punto di prelievo del nuovo viaggio.
vehicle_pickup_straight_line_distance_meter	La distanza in linea retta in metri tra il veicolo e il punto di prelievo del nuovo viaggio.
vehicle_dropoff_eta	L'orario di arrivo stimato del veicolo al punto di destinazione se questo viaggio venisse assegnato al veicolo in questo momento.
vehicle_trips_waypoints	Un elenco dei waypoint rimanenti, inclusi i punti di prelievo e destinazione, per i viaggi attivi attualmente assegnati al veicolo.
vehicle_match_type	Il tipo di viaggio del veicolo, EXCLUSIVE, BACK_TO_BACK, CARPOOL o CARPOOL_BACK_TO_BACK.

Per un elenco completo dei campi VehicleMatch, vedi:

VehicleMatch message (gRPC)
VehicleMatch resource (REST)

Utilizzare le query di filtro

SearchVehicles e ListVehicles supportano il filtraggio degli attributi dei veicoli utilizzando una query di filtro.

Le query di filtro supportano SOLO il filtraggio degli attributi personalizzati per i veicoli e non possono essere utilizzate per altri campi. Se utilizzata in una ricerca che include altri criteri di campo, come minimum_capacity o vehicle_types, la query di filtro funziona come una clausola AND.

Ad esempio, se cerchi un veicolo con una capacità minima di 6 e filtri un attributes come pet-friendly, i tuoi criteri restituiranno solo i veicoli che sono sia pet-friendly sia in grado di trasportare almeno 6 passeggeri.

Per la sintassi delle query di filtro, consulta AIP-160 per esempi. Per i dettagli sulla creazione degli attributi dei veicoli, consulta il campo Attributi dei veicoli nella guida Aggiorna i campi dei veicoli.

Esempio di SearchVehicles

L'esempio seguente mostra come utilizzare l'API SearchVehicles utilizzando la libreria gRPC Java. Per un elenco completo delle lingue supportate, vedi Librerie client per i servizi di viaggio on demand.

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 Jkt 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(Category.AUTO).build())
    .setCurrentTripsPresent(CurrentTripsPresent.ANY)
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .build();

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

List<VehicleMatch> vehicleMatches =
    searchVehicleResponse.getMatchesList();

// Each VehicleMatch contains a Vehicle entity and information about the
// distance and ETA to the pickup point and drop-off point.

Passaggi successivi

DeleteVehicle