作為行動隨選行程服務的一部分,你可以尋找附近的車輛
透過 SearchVehicles
方法處理這些要求
SearchVehicles
方法可讓您在消費者行動應用程式中,找出最適合特定行程或運送要求的附近可用車輛。SearchVehicles
API 會傳回經過排序的車輛清單
屬性與要求的行程屬性相符。排名會依據你選擇的預估抵達時間、距離或與上車地點的直線距離排序。
搜尋屬性 | 車輛屬性 |
---|---|
|
|
使用 SearchVehicles
方法
如要使用 SearchVehicles
,請按照以下一般程序操作:
- 根據要指派的行程建構
SearchVehiclesRequest
。 - 使用建構的要求呼叫
SearchVehicles
API (vehicleService.searchVehicles
)。 - 處理 API 傳回的
SearchVehicleResponse
。
搜尋 VehiclesRequest 欄位
請使用下列必要屬性欄位建構
SearchVehiclesRequest
:
欄位 | 說明 |
---|---|
parent | 必填。格式提供者/{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 | 必填。透過下列其中一種方式訂購車輛:
|
數量 | 必填。傳回的車輛數量上限為 1 到 50 輛。 |
篩選器 | (選用) 搜尋車輛時要套用的篩選查詢。 |
如要查看完整的 SearchVehicleRequest (車輛要求) 欄位。
搜尋 VehiclesRequest 情境
本節會舉例說明如何建構 SearchVehiclesRequest
。
舉例來說,假設客戶希望在 RestaurantX 上車,而你有四輛車輛:
- 車輛 1:距離餐廳 X 3500 公尺。
- 車輛 2:距離 餐廳 X 門市 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
傳回 Vehicle 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 物件,包括 car_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.