路线规划和调度功能是按需乘车和送货解决方案的一部分,可让您通过提供 SearchVehicles
API 来查找附近的司机。
借助 SearchVehicles
API,您可以在自己的按需叫车和送货解决方案消费者应用中找到最适合完成叫车或送餐等任务的附近司机。SearchVehicles
API 会返回一个按顺序排列的司机列表,这些司机将任务属性与您车队中车辆的属性相匹配。
任务属性可以包括:
- 上车点和下车点
- 请求的车辆和行程类型
- 所需容量
- 其他必需的匹配属性
车辆属性可能包括:
- 车辆最近一次的已知位置
- 车辆状态、类型或容量
- 其他自定义属性
排名是根据您选择的预计到达时间、距离或与上车点之间的直线距离进行排序。
请注意,您必须拥有 Fleet Engine Service Super User 或 Consumer SDK User 权限才能使用 SearchVehicles
API。如需了解详情,请参阅身份验证和授权。
使用 SearchVehicles API
如需使用 SearchVehicles
API,请执行以下操作:
- 根据要分配的任务构造
SearchVehiclesRequest
。 - 使用构建的请求调用
SearchVehicles
API (vehicleService.searchVehicles
)。 - 处理从 API 返回的
SearchVehicleResponse
。
SearchVehiclesRequest 字段
使用以下必需的属性字段构造 SearchVehiclesRequest
:
字段 | 说明 |
---|---|
parent | 强制要求。必须采用 provider/{provider} 格式。提供方必须是 Google Cloud 项目(进行此调用的服务账号)所属的 Google Cloud 项目的 ID(例如 sample-cloud-project)。 |
vehicle_types | 强制要求。请求的车辆类型,包括 AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。 |
trip_types | 强制要求。“专有”(每位司机一次一个有效的行程)或“共享”(每位司机一次或多次行程)。 |
minimum_capacity | 强制要求。完成新任务所需的车辆的最小剩余容量,可以是载客,也可以是送货。 |
pickup_point | 强制要求。任务的上车地点(以纬度/经度坐标表示)。 |
dropoff_point | 可选。任务的下车地点(以纬度/经度坐标表示)。 如果 trip_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 米,且距离 RestaurantX 很远还有 1 个下车点。
- 第 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.