搜索车辆

作为按需出行服务的一部分，您可以使用 SearchVehicles 方法查找附近的车辆。

借助 SearchVehicles 方法，您可以在消费者移动应用中找到最适合特定行程或送货请求的附近可用车辆。SearchVehicles API 会返回一个经过排名的车辆列表，其中车辆的属性与所请求行程的属性相匹配。排名顺序取决于您选择的预计到达时间、距离或与上车点的直线距离。

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

使用 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	必需。EXCLUSIVE（每位司机一次只能接一单）或 SHARED（每位司机一次可以接一单或多单）。
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 之间）。
filter	可选。搜索车辆时要应用的过滤查询。
maximum_staleness	可选。将搜索限制为仅搜索在指定时长内向 Fleet Engine 发送过位置信息更新的车辆。如果未设置此字段，服务器会使用 5 分钟作为默认值。

如需查看完整的 SearchVehicleRequest 字段集，请参阅参考文档。

SearchVehiclesRequest 场景

本部分举例说明了如何构造 SearchVehiclesRequest。

例如，假设某位客户想在 RestaurantX 上车，而您有四辆车：

• 车辆 1：距离餐厅 X 3,500 米。
• 车辆 2：距离 RestaurantX 100 米，正在进行行程，上车地点为 A，下车地点为 B。
• 车辆 3：距离 RestaurantX 200 米，剩余的送达地点非常远。
• 车辆 4：距离 RestaurantX 1000 米。

以下内容按车辆返回结果显示了各种请求。

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 示例

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

后续步骤

• DeleteVehicle