Como parte do serviço de viagem on demand do Mobility, é possível encontrar veículos por perto usando o método SearchVehicles.
O método SearchVehicles permite encontrar veículos disponíveis por perto no seu app para dispositivos móveis do consumidor que sejam mais adequados para uma viagem ou um pedido de entrega específico. A API SearchVehicles retorna uma lista classificada de veículos com
atributos que correspondem aos atributos da viagem solicitada. A classificação é ordenada por sua escolha de HEC, distância ou distância em linha reta do ponto de retirada.
| Atributos de pesquisa | Atributos do veículo |
|---|---|
|
|
Use o método SearchVehicles
Para usar o SearchVehicles, siga este processo geral:
- Crie um
SearchVehiclesRequestcom base na viagem a ser atribuída. - Chame a API
SearchVehicles(vehicleService.searchVehicles) com a solicitação criada. - Processe o
SearchVehicleResponseretornado pela API.
Campos de SearchVehiclesRequest
Use os seguintes campos de atributo obrigatórios para criar um
SearchVehiclesRequest:
| Campo | Descrição |
|---|---|
| familiar responsável | Obrigatório. Precisa estar no formato providers/{provider}. O provedor precisa ser o ID do projeto na nuvem do Google Cloud em que a conta de serviço que faz essa chamada é membro. |
| vehicle_types | Obrigatório. Tipos de veículos solicitados: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE ou PEDESTRIAN. |
| trip_types | Obrigatório. EXCLUSIVE (uma viagem ativa por vez por motorista) ou SHARED (uma ou várias viagens por vez por motorista). |
| minimum_capacity | Obrigatório. A capacidade mínima restante do veículo para uma nova viagem, seja para passageiros ou entregas. |
| pickup_point | Obrigatório. O local de retirada da viagem em coordenadas de latitude/longitude. |
| dropoff_point | Opcional. O local de desembarque da viagem em coordenadas de latitude/longitude. O campo é obrigatório se trip_types contém TripType.SHARED. |
| pickup_radius_meters | Obrigatório. O raio em metros da área de pesquisa de veículos do ponto de partida. |
| order_by | Obrigatório. Ordene os veículos por uma das seguintes opções:
|
| contagem | Obrigatório. O número máximo de veículos a serem retornados, de 1 a 50. |
| filtro | Opcional. Uma consulta de filtro para aplicar ao pesquisar veículos. |
| maximum_staleness | Opcional. Restringe a pesquisa apenas aos veículos que enviaram atualizações do local ao Fleet Engine no período especificado. Se esse campo não for definido, o servidor usará cinco minutos como o valor padrão. |
Consulte a documentação de referência para ver o conjunto completo de campos de SearchVehicleRequest.
Cenários de SearchVehiclesRequest
Esta seção mostra exemplos de como criar um SearchVehiclesRequest.
Por exemplo, suponha que um cliente queira ser buscado no RestauranteX e você tenha quatro veículos:
- Veículo 1: a 3.500 m do RestauranteX.
- Veículo 2: a 100 m do RestauranteX, com uma viagem ativa com retirada e entrega nos locais A e B.
- Veículo 3: a 200 m do RestauranteX, com uma entrega restante muito distante.
- Veículo 4: a 1.000 m do RestauranteX.
Veja a seguir várias solicitações pelo veículo que elas retornam.
Retorna o veículo 4
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA
Retorna os veículos 3 e 4
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled
Retorna os veículos 2, 3 e 4
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL
Campos de SearchVehiclesResponse
Um SearchVehiclesResponse consiste em uma lista de entidades VehicleMatch, classificadas
pelo atributo order_by especificado no SearchVehiclesRequest. Cada entidade VehicleMatch tem os seguintes campos:
| Campo | Descrição |
|---|---|
| veículo | O objeto Vehicle, incluindo os atributos vehicle_id e Vehicle. |
| vehicle_pickup_eta | O HEC do veículo no local de retirada se essa viagem fosse atribuída ao veículo agora. |
| vehicle_pickup_distance_meter | A distância em metros entre o veículo e o local de retirada da nova viagem. |
| vehicle_pickup_straight_line_distance_meter | A distância em linha reta, em metros, entre o veículo e o local de retirada da nova viagem. |
| vehicle_dropoff_eta | O HEC do veículo no local de desembarque se essa viagem fosse atribuída ao veículo agora. |
| vehicle_trips_waypoints | Uma lista de waypoints restantes, incluindo pontos de retirada e entrega, para as viagens ativas atribuídas ao veículo. |
| vehicle_match_type | O tipo de viagem do veículo, que pode ser EXCLUSIVE, BACK_TO_BACK, CARPOOL ou CARPOOL_BACK_TO_BACK. |
Para uma lista completa de campos VehicleMatch, consulte:
VehicleMatch message(gRPC)VehicleMatch resource(REST)
Usar consultas de filtro
SearchVehicles e ListVehicles são compatíveis com a filtragem de atributos de veículos
usando uma consulta de filtro.
As consultas de filtro SÓ são compatíveis com a filtragem de atributos personalizados para veículos e
não podem ser usadas para outros campos. Quando usada em uma pesquisa que inclui outros critérios de campo, como minimum_capacity ou vehicle_types, a consulta de filtro funciona como uma cláusula AND.
Por exemplo, se você pesquisar um veículo com capacidade mínima de 6 pessoas e
filtrar um attributes, como "aceita animais de estimação", os critérios vão retornar apenas
os veículos que aceitam animais de estimação e podem transportar pelo menos 6 passageiros.
Para ver a sintaxe da consulta de filtro, consulte AIP-160 para ver exemplos. Para detalhes sobre como criar atributos de veículo, consulte Campo de atributos de veículo no guia Atualizar campos de veículo.
Exemplo de SearchVehicles
O exemplo a seguir mostra como usar a API SearchVehicles com a
biblioteca gRPC do Java. Para ver uma lista completa de idiomas compatíveis, consulte
Bibliotecas de cliente para serviços de viagem 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.