搜尋車輛

您可以使用 SearchVehicles 方法，透過 Mobility on-demand 行程服務尋找附近的車輛。

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 輛。
篩選器	(選用) 搜尋車輛時要套用的篩選器查詢。

如需 SearchVehicleRequest 欄位的完整清單，請參閱參考說明文件。

SearchVehiclesRequest 情境

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

舉例來說，假設客戶希望在 RestaurantX 上車，而你有四輛車輛：

• 車輛 1：距離餐廳 X 3500 公尺。
• 車輛 2：位於 RestaurantX 100 公尺處，有 A 和 B 地點的上下車點和有效行程。
• 車輛 3：距離餐廳 X 200 公尺，且還有一個非常遠的下車地點。
• 車輛 4：距離餐廳 X 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.

後續步驟

• 建立隨選行程