此页面由 Cloud Translation API 翻译。

搜索车辆

在 Mobility 按需行程服务中，您可以使用 SearchVehicles 方法查找附近的车辆。

借助 SearchVehicles 方法，您可以在面向消费者的移动应用中查找附近最适合特定乘车或送货请求的空闲车辆。SearchVehicles API 会返回属性与所请求行程属性匹配的车辆的排序列表。排名依据您选择的预计到达时间、距离或与上车点之间的直线距离而定。

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

使用 `SearchVehicles` 方法

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

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

SearchVehiclesRequest 字段

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

字段	说明
父级	必需。必须采用 provider/{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)

使用过滤器查询

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.

后续步骤

创建按需行程