搜索车辆

作为移动按需行程服务的一部分,您可以查找附近的车辆 使用 SearchVehicles 方法指定价格属性。

借助 SearchVehicles 方法,您可以查找附近可用的车辆, 最适合提供特定叫车或送餐服务的消费者移动应用 请求。SearchVehicles API 会返回一个按顺序排列的车辆, 属性与所请求的行程属性匹配。排名按照您的 可以选择预计到达时间、距离或与上车点之间的直线距离。

搜索属性 车辆属性
  • 上车点和下车点
  • 请求的车辆和行程类型
  • 所需容量
  • 其他必需的匹配属性
  • 车辆最近一次的已知位置
  • 车辆状态、类型或容量
  • 其他自定义属性

使用 SearchVehicles 方法

如需使用 SearchVehicles,请按以下常规流程操作:

  1. 根据要分配的行程构造 SearchVehiclesRequest
  2. 使用以下代码调用 SearchVehicles API (vehicleService.searchVehicles) 构建请求。
  3. 处理从 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 必需。通过以下任一方式订购车辆:
  • PICKUP_POINT_ETA,车辆在上车点的预计到达时间。
  • PICKUP_POINT_DISTANCE,车辆与上车点之间的距离。
  • DROPOFF_POINT_ETA,即车辆在下车点完成行程的预计到达时间。
  • PICKUP_POINT_STRAIGHT_DISTANCE,车辆与上车点之间的直线距离(不在路线中)。
计数 必需。要返回的车辆数量上限(从 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 字段

SearchVehiclesResponseVehicleMatch 实体列表组成,这些实体按顺序排列 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 字段的完整列表,请参阅:

使用过滤查询

SearchVehiclesListVehicles 支持根据车辆属性进行过滤 使用过滤条件查询

过滤查询仅支持根据车辆的自定义属性进行过滤,并且 不能用于其他字段。在包含其他字段的搜索中使用时 条件(如 minimum_capacityvehicle_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.

后续步骤