Como parte de tu solución On-demand Rides & Deliveries, la función de planificación de rutas y despacho te permite encontrar conductores cercanos proporcionando una API de SearchVehicles.
La API de SearchVehicles te permite encontrar conductores cercanos disponibles en la app para consumidores de la solución On-demand Rides & Deliveries que se adapten mejor a una tarea, como un viaje o una solicitud de entrega. La API de SearchVehicles muestra una lista clasificada de conductores que coinciden con los atributos de tareas con los atributos de los vehículos de tu flota.
Los atributos de las tareas pueden incluir lo siguiente:
- Ubicaciones de partida y llegada
- Tipos de viaje y vehículo solicitados
- Capacidad requerida
- Otros atributos de coincidencia obligatorios
Entre los atributos de vehículos, se incluyen los siguientes:
- La última ubicación conocida de un vehículo
- El estado, el tipo o la capacidad del vehículo
- Otros atributos personalizados
La clasificación se ordena según tu elección de la hora de llegada estimada, la distancia o la distancia en línea recta desde el punto de partida.
Ten en cuenta que debes tener privilegios de superusuario o de usuario del SDK de consumidor del servicio de Fleet Engine para usar la API de SearchVehicles. Para obtener más información, consulta Autenticación y autorización.
Cómo usar la API de SearchVehicles
Para usar la API de SearchVehicles, haz lo siguiente:
- Crea un
SearchVehiclesRequestbasado en la tarea que se asignará. - Llama a la API de
SearchVehicles(vehicleService.searchVehicles) con la solicitud construida. - Procesa el
SearchVehicleResponseque muestra la API.
Campos de SearchVehiclesRequest
Usa los siguientes campos de atributos obligatorios para construir un SearchVehiclesRequest:
| Campo | Descripción |
|---|---|
| parent | Obligatorio: Debe estar en el formato providers/{provider}. El proveedor debe ser el ID del proyecto (por ejemplo, sample-cloud-project) del proyecto de Google Cloud al que pertenece la cuenta de servicio que realiza esta llamada. |
| vehicle_types | Obligatorio: Se solicitan tipos de vehículos: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE o PEDESTRIAN. |
| trip_types | Obligatorio: Puede ser EXCLUSIVO (un viaje activo a la vez por conductor) o COMPARTIDO (uno o varios viajes a la vez por conductor). |
| minimum_capacity | Obligatorio: Es la capacidad mínima restante del vehículo para una tarea nueva, ya sea para pasajeros o entregas. |
| pickup_point | Obligatorio: El lugar de partida de la tarea en coordenadas de latitud y longitud. |
| dropoff_point | Opcional. La ubicación de destino de la tarea en coordenadas de latitud y longitud. El campo es obligatorio si trip_types contiene TripType.SHARED. |
| pickup_radius_meters | Obligatorio: El radio en metros del área de búsqueda del vehículo desde el punto de partida. |
| order_by | Obligatorio: Ordena los vehículos de una de las siguientes maneras:
|
| recuento | Obligatorio: La cantidad máxima de vehículos que se deben devolver de 1 a 50. |
Consulta la documentación de referencia para ver el conjunto completo de SearchVehicleRequestfields.
Ejemplos de SearchVehiclesRequest
En esta sección, se muestran ejemplos de cómo construir un SearchVehiclesRequest.
Por ejemplo, supongamos que tienes una tarea de recogida para asignar en RestaurantX y cuatro vehículos:
- Vehículo 1, que está a 3,500 m de distancia de RestaurantX.
- Vehículo 2, que está a 100 m de RestaurantX y tiene un viaje activo con partida y llegada en las ubicaciones A y B.
- Vehículo 3, que está a 200 m de RestaurantX y al que le queda una parada muy lejos.
- Vehículo 4, que está a 1,000 m de distancia de RestaurantX.
El siguiente SearchVehiclesRequest devuelve el vehículo 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA
El siguiente SearchVehiclesRequest devuelve los vehículos 3 y 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled
El siguiente SearchVehiclesRequest muestra los vehículos 2, 3 y 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL
Campos SearchVehiclesResponse
Un SearchVehiclesResponse consiste en una lista de entidades VehicleMatch, clasificadas por el atributo order_by especificado en SearchVehiclesRequest.
Cada entidad VehicleMatch tiene los siguientes campos:
| Campo | Descripción |
|---|---|
| vehículo | El objeto Vehicle, incluidos los atributos id_vehículo y Vehicle |
| vehicle_pickup_eta | La hora de llegada estimada del vehículo en el lugar de recogida de la tarea nueva. Esta es la hora de llegada estimada en la que se conduce. |
| vehicle_pickup_distance_meter | La distancia en metros entre el vehículo y el lugar de recogida de la nueva tarea. |
| vehicle_pickup_straight_line_distance_meter | La distancia en línea recta en metros entre el vehículo y el lugar de recogida de la nueva tarea. |
| vehicle_dropoff_eta | La marca de tiempo de la hora de llegada estimada del vehículo en la ubicación de partida de la tarea nueva. Ten en cuenta que la hora de llegada estimada es la hora de llegada estimada en formato en automóvil. |
| vehicle_trips_waypoints | Una lista de los puntos de referencia restantes, incluidos los puntos de partida y llegada, para los viajes activos actualmente asignados al vehículo. |
| vehicle_match_type | El tipo de viaje del vehículo, ya sea EXCLUSIVE, BACK_TO_BACK, CARPOOL o CARPOOL_BACK_TO_BACK. |
Ejemplo de SearchVehicles
En el siguiente ejemplo, se muestra cómo usar la API de SearchVehicles:
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.