搜索车辆

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

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

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

注意 ：您必须拥有 Fleet Engine On-demand Admin 或 Consumer SDK User 使用 SearchVehicles API 的权限。如需了解详情，请参阅 Fleet Engine 服务账号角色。

使用 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 字段

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)

注意： 车辆必须处于在线状态（具有 vehicle_state=ONLINE），才能被搜到并 SearchVehicles 返回的值。

使用过滤查询

SearchVehicles 和 ListVehicles 支持根据车辆属性进行过滤 使用过滤条件查询。

过滤查询仅支持根据车辆的自定义属性进行过滤，并且 不能用于其他字段。在包含其他字段的搜索中使用时 条件（如 minimum_capacity 或 vehicle_types），则过滤条件查询 作为 AND 子句。

例如，如果您搜索的一辆车的容量最低为 6， 过滤 attributes（例如允许宠物），您的条件将仅返回 允许携带宠物且至少搭载 6 名乘客的车辆。

如需了解过滤条件查询语法，请参阅 AIP-160 获取示例。如需详细了解如何创建车辆属性，请参阅车辆 更新车辆字段指南中的“属性”字段部分。

注意 ：最佳做法是，在执行下列操作时避免使用以下属性字段 发出过滤条件查询：required_attributes、required_one_of_attributes 或 required_one_of_attributes_sets。而是改为使用 filter 字段， 将替换这些字段。此外，如果您的 请求同时在 filter 字段和另一个属性中指定值 字段。

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.

后续步骤

• 创建按需行程