作为按需行程和配送解决方案的一部分,路线规划和调度功能可让您通过提供 SearchVehicles
API 来查找附近的司机。
借助 SearchVehicles
API,您可以在按需行程和配送解决方案消费者应用中查找附近最适合某项任务(例如约车或配送请求)的司机。SearchVehicles
API 会返回一个按任务属性与车队中车辆属性匹配的驾驶员列表。
任务属性可包括:
- 上车点和下车点
- 请求的车辆和行程类型
- 所需容量
- 其他必需的匹配属性
车辆属性可能包括:
- 车辆最近一次的已知位置
- 车辆状态、类型或容量
- 其他自定义属性
系统会根据您选择的预计到达时间、距离或与上车点的直线距离排序。
请注意,您必须拥有 Fleet Engine 服务超级用户或消费者 SDK 用户权限,才能使用 SearchVehicles
API。如需了解详情,请参阅身份验证和授权。
使用 SearchVehicles API
如需使用 SearchVehicles
API,请执行以下操作:
- 根据要分配的任务构造
SearchVehiclesRequest
。 - 使用构造的请求调用
SearchVehicles
API (vehicleService.searchVehicles
)。 - 处理从 API 返回的
SearchVehicleResponse
。
SearchVehiclesRequest 字段
使用以下必需的属性字段构造 SearchVehiclesRequest
:
字段 | 说明 |
---|---|
parent | 强制要求。必须采用此格式提供程序/{provider}。提供方必须是进行此调用的服务帐号所属的 Google Cloud 项目的 ID(例如 sample-cloud-project)。 |
vehicle_types | 强制要求。请求的车辆类型:AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。 |
trip_types | 强制要求。独占(每位司机一次有效行程一次)或共享(每位司机一次行程一次或多次)。 |
minimum_capacity | 强制要求。执行新任务(无论是乘客还是送货)的车辆最小剩余容量。 |
pickup_point | 强制要求。任务的开始位置(以纬度/经度坐标表示)。 |
dropoff_point | 可选。任务的下车点(以纬度/经度坐标表示)。 如果 travel_types 包含 TripType.SHARED ,则此字段是必填字段。 |
pickup_radius_meters | 强制要求。车辆搜索区域以上车点为起点的半径(以米为单位)。 |
order_by | 强制要求。按以下一种方式订购车辆:
|
计数 | 强制要求。可返回的车辆数量上限在 1 到 50 之间。 |
如需了解完整的 SearchVehicleRequestfields,请参阅参考文档。
SearchVehiclesRequest 示例
本部分举例说明了如何构造 SearchVehiclesRequest
。
例如,假设您有一个取货任务,要分配给 RestaurantX 和四辆车:
- 车辆 1,距离 RestaurantX 3500 米。
- 车辆 2,距离 RestaurantX 100 米,目前正在进行行程,在地点 A 和 B 安排上车点和下车点。
- 车辆 3,距离 RestaurantX 200 米,还留有一个下车点,距离非常远。
- 车辆 4,距离 RestaurantX 1000 米。
以下 SearchVehiclesRequest
会返回车辆 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA
以下 SearchVehiclesRequest
会返回车辆 3 和 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled
以下 SearchVehiclesRequest
会返回车辆 2、3 和 4:
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL
SearchVehiclesResponse 字段
SearchVehiclesResponse
由一系列 VehicleMatch
实体组成,并按 SearchVehiclesRequest
中指定的 order_by 属性排序。每个 VehicleMatch
实体都包含以下字段:
字段 | 说明 |
---|---|
车辆 | Vehicle 对象,包括 vehicle_id 和 Vehicle 属性。 |
vehicle_pickup_eta | 车辆在新任务的上车点的预计到达时间。这是驾车的预计到达时间。 |
vehicle_pickup_distance_meter | 车辆与新任务的取货位置之间的距离(以米为单位)。 |
vehicle_pickup_straight_line_distance_meter | 车辆与新任务的取货位置之间的直线距离(以米为单位)。 |
vehicle_dropoff_eta | 在新任务的上车点,车辆预计到达时间的时间戳。请注意,预计到达时间是指驾车的预计到达时间。 |
vehicle_trips_waypoints | 当前分配给车辆的有效行程的其余航点列表,包括上车点和下车点。 |
vehicle_match_type | 车辆的行程类型,可以是 EXCLUSIVE、BACK_TO_BACK、CARPOOL 或 CARPOOL_BACK_TO_BACK。 |
SearchVehicles 示例
以下示例展示了如何使用 SearchVehicles
API:
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.