作为移动按需行程服务的一部分,您可以查找附近的车辆
使用 SearchVehicles
方法指定价格属性。
借助 SearchVehicles
方法,您可以查找附近可用的车辆,
最适合提供特定叫车或送餐服务的消费者移动应用
请求。SearchVehicles
API 会返回一个按顺序排列的车辆,
属性与所请求的行程属性匹配。排名按照您的
可以选择预计到达时间、距离或与上车点之间的直线距离。
搜索属性 | 车辆属性 |
---|---|
|
|
使用 SearchVehicles
方法
如需使用 SearchVehicles
,请按以下常规流程操作:
- 根据要分配的行程构造
SearchVehiclesRequest
。 - 使用以下代码调用
SearchVehicles
API (vehicleService.searchVehicles
) 构建请求。 - 处理从 API 返回的
SearchVehicleResponse
。
SearchVehiclesRequest 字段
使用以下必需属性字段来构造
SearchVehiclesRequest
:
字段 | 说明 |
---|---|
父级 | 必需。必须采用 provider/{provider} 格式。提供方必须是 Google Cloud 项目(进行此调用的服务账号)所属的 Google Cloud 项目的 ID。 |
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)。 |
过滤 | 可选。搜索车辆时要应用的过滤条件查询。 |
请参阅参考文档, SearchVehicleRequest 字段。
SearchVehiclesRequest 场景
本部分举例说明了如何构造 SearchVehiclesRequest
。
例如,假设一位客户想到 RestaurantX 接餐, 你有四辆车:
- 车辆 1:距离 RestaurantX 3500 米。
- 车辆 2:距离 RestaurantX 100 米,且目前正在进行带自提的行程 在地点 A 和 B 下车。
- 车辆 3:距离 RestaurantX 200 米,还剩 1 辆下车点 距离较远
- 车辆 4:距离 RestaurantX 1000 米。
下面按照返回的车辆显示各种请求。
退回第 4 辆车
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA
退还第 3 和第 4 辆车
Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled
退回车辆 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。 |
如需查看 VehicleMatch
字段的完整列表,请参阅:
VehicleMatch message
(gRPC)VehicleMatch resource
(REST)
使用过滤查询
SearchVehicles
和 ListVehicles
支持根据车辆属性进行过滤
使用过滤条件查询。
过滤查询仅支持根据车辆的自定义属性进行过滤,并且
不能用于其他字段。在包含其他字段的搜索中使用时
条件(如 minimum_capacity
或 vehicle_types
),则过滤条件查询
作为 AND
子句。
例如,如果您搜索的一辆车的容量最低为 6,
过滤 attributes
(例如允许宠物),您的条件将仅返回
允许携带宠物且至少搭载 6 名乘客的车辆。
如需了解过滤条件查询语法,请参阅 AIP-160 获取示例。如需详细了解如何创建车辆属性,请参阅车辆 更新车辆字段指南中的“属性”字段部分。
SearchVehicles 示例
以下示例展示了如何通过SearchVehicles
Java gRPC 库。
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.