搜索车辆

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

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

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

注意：您必须拥有 Fleet Engine 按需管理员或 Consumer SDK 用户权限，才能使用 SearchVehicles API。如需了解详情，请参阅 Fleet Engine 服务账号角色。

使用 SearchVehicles 方法

如需使用 SearchVehicles，请按以下常规流程操作：

1. 根据要分配的行程构建 SearchVehiclesRequest。
2. 使用构建的请求调用 SearchVehicles API (vehicleService.searchVehicles)。
3. 处理从 API 返回的 SearchVehicleResponse。

SearchVehiclesRequest 字段

使用以下必需的属性字段构建 SearchVehiclesRequest：

字段	说明
父级	必需。必须采用 providers/{provider} 格式。提供方必须是 Google Cloud 项目（进行此调用的服务账号）所属的 Google Cloud 项目的 ID。
vehicle_types	必需。请求的车辆类型，包括 AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。
trip_types	必需。专享（每位司机一次只能有一项有效行程）或共享（每位司机一次可以有 1 项或多项有效行程）。
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 示例

以下示例展示了如何使用 Java gRPC 库使用 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.

后续步骤

• 创建按需行程