搜尋車輛

您可以使用 SearchVehicles 方法，在隨選交通服務中尋找附近的車輛。

SearchVehicles 方法可讓你在消費者行動應用程式中，尋找附近最適合特定行程或外送要求的可用車輛。SearchVehicles API 會傳回車輛的排序清單，這些車輛的屬性符合要求的行程屬性。排名順序取決於你選擇的預計抵達時間、距離或與取貨地點的直線距離。

搜尋屬性	車輛屬性
取車和還車地點 要求的車輛和行程類型 所需容量 其他必要配對屬性	車輛的最後已知位置 車輛狀態、類型或容量 其他自訂屬性

使用 SearchVehicles 方法

如要使用 SearchVehicles，請按照下列一般程序操作：

1. 根據要指派的行程建構 SearchVehiclesRequest。
2. 使用建構的要求呼叫 SearchVehicles API (vehicleService.searchVehicles)。
3. 處理 API 傳回的 SearchVehicleResponse。

SearchVehiclesRequest 欄位

請使用下列必要屬性欄位建構 SearchVehiclesRequest：

欄位	說明
parent	必填。格式必須為 providers/{provider}。提供者必須是 Google Cloud 專案的專案 ID，而發出這項呼叫的服務帳戶是該專案的成員。
vehicle_types	必填。要求的車輛類型，可以是 AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。
trip_types	必填。可選擇「專屬」(每位駕駛人一次只能接一趟行程) 或「共乘」(每位駕駛人一次可接一或多趟行程)。
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。
篩選	(選用) 搜尋車輛時要套用的篩選查詢。
maximum_staleness	(選用) 將搜尋範圍限制為在指定時間內向 Fleet Engine 傳送位置更新的車輛。如果未設定這個欄位，伺服器會使用五分鐘做為預設值。

如要查看完整的 SearchVehicleRequest 欄位，請參閱參考說明文件。

SearchVehiclesRequest 情境

本節將舉例說明如何建構 SearchVehiclesRequest。

舉例來說，假設顧客想在 RestaurantX 上車，而您有四輛車：

• 車輛 1：距離 RestaurantX 3500 公尺。
• 車輛 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