Cerca veicoli

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

Il metodo SearchVehicles ti consente di trovare 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 a quelli del viaggio richiesto. Il ranking è ordinato in base alla tua scelta tra ETA, distanza o distanza in linea retta dal punto di ritiro.

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

Nota :per utilizzare l'API SearchVehicles, devi disporre dei privilegi di amministratore di Fleet Engine On-demand o di utente SDK consumer. Per saperne di più, consulta Ruoli del service account Fleet Engine.

Utilizzare il metodo SearchVehicles

Per utilizzare SearchVehicles, segui questa procedura generale:

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

Campi SearchVehiclesRequest

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

Campo	Descrizione
principale	Required. Deve essere nel formato providers/{provider}. Il fornitore deve essere l'ID progetto del progetto Google Cloud di cui è membro il service account che effettua questa chiamata.
vehicle_types	Required. Tipi di veicoli richiesti: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE o PEDESTRIAN.
trip_types	Required. ESCLUSIVO (un viaggio attivo alla volta per autista) o CONDIVISO (uno o più viaggi alla volta per autista).
minimum_capacity	Required. La capacità residua minima del veicolo per un nuovo viaggio, per passeggeri o consegne.
pickup_point	Required. Il punto di partenza del viaggio in coordinate di latitudine/longitudine.
dropoff_point	(Facoltativo) Il punto di discesa della corsa in coordinate di latitudine/longitudine. Il campo è obbligatorio se trip_types contiene TripType.SHARED.
pickup_radius_meters	Required. Il raggio in metri dell'area di ricerca del veicolo dal punto di partenza.
order_by	Required. Ordina i veicoli in base a uno dei seguenti criteri: PICKUP_POINT_ETA, l'orario di arrivo stimato del veicolo al punto di partenza. PICKUP_POINT_DISTANCE, la distanza tra il veicolo e il punto di prelievo. DROPOFF_POINT_ETA, l'ETA del veicolo per completare il viaggio al punto di riconsegna. PICKUP_POINT_STRAIGHT_DISTANCE, la distanza in linea retta (non nel percorso) tra il veicolo e il punto di prelievo.
conteggio	Required. Il numero massimo di veicoli da restituire, da 1 a 50.
filtro	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 campi SearchVehicleRequest.

Scenari di SearchVehiclesRequest

Questa sezione mostra esempi di come creare un SearchVehiclesRequest.

Ad esempio, supponiamo che un cliente voglia essere prelevato al ristorante X e che tu abbia quattro veicoli:

• Veicolo 1: a 3500 m di distanza da RistoranteX.
• Veicolo 2: a 100 metri dal ristorante X con un viaggio attivo con ritiro e consegna nelle località A e B.
• Veicolo 3: a 200 metri dal ristorante X con una consegna rimanente molto lontana.
• Veicolo 4: a 1000 m dal ristorante X.

Di seguito vengono visualizzate varie richieste in base al veicolo che restituiscono.

Returns Vehicle 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
Veicolo	L'oggetto Vehicle, inclusi gli attributi vehicle_id e Vehicle.
vehicle_pickup_eta	L'ETA del veicolo presso il luogo di ritiro se questo viaggio venisse assegnato al veicolo in questo momento.
vehicle_pickup_distance_meter	La distanza in metri tra il veicolo e il luogo di prelievo della nuova corsa.
vehicle_pickup_straight_line_distance_meter	La distanza in linea retta in metri tra il veicolo e il luogo di partenza del nuovo viaggio.
vehicle_dropoff_eta	L'orario di arrivo stimato del veicolo nella località di riconsegna se questa corsa venisse assegnata al veicolo in questo momento.
vehicle_trips_waypoints	Un elenco dei waypoint rimanenti, inclusi i punti di prelievo e arrivo, 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)

Nota: un veicolo deve essere online (con vehicle_state=ONLINE) per essere ricercabile e restituito da SearchVehicles.

Utilizzare le query di filtro

SearchVehicles e ListVehicles supportano il filtraggio in base agli attributi del veicolo utilizzando una query con filtro.

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

Ad esempio, se cerchi un veicolo con una capacità minima di 6 persone e filtri un attributes come "animali domestici ammessi", i tuoi criteri restituiranno solo i veicoli che ammettono animali domestici e possono trasportare almeno 6 passeggeri.

Per la sintassi delle query di filtro, consulta AIP-160 per esempi. Per informazioni dettagliate sulla creazione degli attributi del veicolo, consulta la sezione Campo attributi del veicolo nella guida Aggiornare i campi del veicolo.

Nota :come best practice, evita l'utilizzo dei seguenti campi degli attributi quando emetti una query di filtro: required_attributes, required_one_of_attributes o required_one_of_attributes_sets. Utilizza invece il campo filter, che sostituisce questi campi. Inoltre, riceverai un errore se la tua richiesta specifica un valore sia nel campo filter sia negli altri campi dell'attributo.

Esempio di SearchVehicles

L'esempio seguente mostra come utilizzare l'API SearchVehicles utilizzando la libreria gRPC 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 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