正在查找附近的司机

作为按需行程和配送解决方案的一部分，路线规划和调度功能可让您通过提供 SearchVehicles API 来查找附近的司机。

借助 SearchVehicles API，您可以在按需行程和配送解决方案消费者应用中查找附近最适合某项任务（例如约车或配送请求）的司机。SearchVehicles API 会返回一个按任务属性与车队中车辆属性匹配的驾驶员列表。

任务属性可包括：

• 上车点和下车点
• 请求的车辆和行程类型
• 所需容量
• 其他必需的匹配属性

车辆属性可能包括：

• 车辆最近一次的已知位置
• 车辆状态、类型或容量
• 其他自定义属性

系统会根据您选择的预计到达时间、距离或与上车点的直线距离排序。

请注意，您必须拥有 Fleet Engine 服务超级用户或消费者 SDK 用户权限，才能使用 SearchVehicles API。如需了解详情，请参阅身份验证和授权。

使用 SearchVehicles API

如需使用 SearchVehicles API，请执行以下操作：

• 根据要分配的任务构造 SearchVehiclesRequest。
• 使用构造的请求调用 SearchVehicles API (vehicleService.searchVehicles)。
• 处理从 API 返回的 SearchVehicleResponse。

SearchVehiclesRequest 字段

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

字段	说明
parent	强制要求。必须采用此格式提供程序/{provider}。提供方必须是进行此调用的服务帐号所属的 Google Cloud 项目的 ID（例如 sample-cloud-project）。
vehicle_types	强制要求。请求的车辆类型：AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。
trip_types	强制要求。独占（每位司机一次有效行程一次）或共享（每位司机一次行程一次或多次）。
minimum_capacity	强制要求。执行新任务（无论是乘客还是送货）的车辆最小剩余容量。
pickup_point	强制要求。任务的开始位置（以纬度/经度坐标表示）。
dropoff_point	可选。任务的下车点（以纬度/经度坐标表示）。 如果 travel_types 包含 TripType.SHARED ，则此字段是必填字段。
pickup_radius_meters	强制要求。车辆搜索区域以上车点为起点的半径（以米为单位）。
order_by	强制要求。按以下一种方式订购车辆： PICKUP_POINT_ETA，车辆在上车点的预计到达时间。 PICKUP_POINT_DISTANCE，车辆与上车点之间的距离。 DROPOFF_POINT_ETA，车辆将在下车点完成行程的预计到达时间。 PICKUP_POINT_STRAIGHT_DISTANCE，车辆与上车点之间的直线距离（不在路线中）。
计数	强制要求。可返回的车辆数量上限在 1 到 50 之间。

如需了解完整的 SearchVehicleRequestfields，请参阅参考文档。

SearchVehiclesRequest 示例

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

例如，假设您有一个取货任务，要分配给 RestaurantX 和四辆车：

• 车辆 1，距离 RestaurantX 3500 米。
• 车辆 2，距离 RestaurantX 100 米，目前正在进行行程，在地点 A 和 B 安排上车点和下车点。
• 车辆 3，距离 RestaurantX 200 米，还留有一个下车点，距离非常远。
• 车辆 4，距离 RestaurantX 1000 米。

以下 SearchVehiclesRequest 会返回车辆 4：

Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

以下 SearchVehiclesRequest 会返回车辆 3 和 4：

Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

以下 SearchVehiclesRequest 会返回车辆 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。

注意 ：车辆必须处于在线状态（即，Vehicle_state=Online）才可被 SearchVehicles 搜索并返回。

SearchVehicles 示例

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