搜索车辆

在 Mobility 按需行程服务中，您可以使用 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 项目的项目 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 上车，而您有 4 辆车：

• 车辆 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.

后续步骤

• 创建随叫随到行程