隨選乘車和配送解決方案的其中一項功能是「路線規劃與調度」功能，只要提供 SearchVehicles API，即可尋找附近的司機。
SearchVehicles API 可讓您在隨選即用的「乘車服務」和「外送服務」應用程式消費者應用程式中，找到最適合執行叫車或外送工作等工作的司機。SearchVehicles API 會傳回與機群中的車輛屬性相符工作屬性的驅動程式排名清單。
工作屬性可包含：
- 上車和下車地點
- 要求的車輛和行程類型
- 所需容量
- 其他必要的比對屬性
車輛屬性包括：
- 車輛的最後已知位置
- 車輛狀態、類型或容量
- 其他自訂屬性
系統會依據您選擇的預計到達時間、距離或直線距離，決定與乘車地點之間的距離排序。
請注意，您必須具備 Fleet Engine 服務超級使用者或 Consumer SDK 使用者權限，才能使用 SearchVehicles API。詳情請參閱驗證與授權。
使用 SearchVehicles API
如何使用 SearchVehicles API：
- 根據要指派的工作建構
SearchVehiclesRequest。 - 使用建構的要求呼叫
SearchVehiclesAPI (vehicleService.searchVehicles)。 - 處理 API 傳回的
SearchVehicleResponse。
搜尋 VehiclesRequest 欄位
請使用下列必要屬性欄位建構 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 | 選用設定。工作的下車地點，以經緯度座標表示。如果行程_types 包含 TripType.SHARED，則此為必填欄位。 |
| pickup_radius_meters | 必填。從上車地點的車輛搜尋區域半徑 (以公尺為單位)。 |
| order_by | 必填。透過下列任一方式訂購車輛：
|
| 數量 | 必填。可退貨的車輛數量上限 (1 至 50 個)。 |
如要查看 SearchVehicleRequestfields 的完整組合，請參閱參考說明文件。
SearchVehiclesRequest 範例
本節會舉例說明如何建構 SearchVehiclesRequest。
舉例來說，假設您在 RestaurantX 和四輛車安排了一項上車任務：
- 車輛 1，距離 3500 公尺 (餐廳 X) 距離。
- 車輛 2，距離 RestaurantX 100 公尺，提供正在乘車的 A 和 B 地點上車和下車服務。
- 車輛 3，距離餐廳 X 200 公尺，僅剩 1 號下車。
- 車輛 4，距離餐廳 X 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
搜尋 VehiclesResponse 欄位
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。 |
搜尋車輛範例
以下範例說明如何使用 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.