做為隨選乘車和運送服務解決方案的一部分，路線規劃和調度功能功能可讓您提供 SearchVehicles API，以便尋找附近的司機。
透過 SearchVehicles API，您可以在「隨選乘車與外送解決方案」消費者應用程式中，找出最適合用來叫車或送貨要求等工作的司機。SearchVehicles API 會傳回一份排序清單，列出與車隊中車輛屬性相符的任務屬性。
工作屬性可包含：
- 上車和下車地點
- 要求的車輛和行程類型
- 需要的容量
- 其他必要的相符屬性
車輛屬性可包含：
- 車輛的最後已知位置
- 車輛狀態、類型或容量
- 其他自訂屬性
排名順序取決於您在上車地點的預計到達時間、距離或直線距離。
請注意，您必須具備 Fleet Engine 服務超級使用者或消費者 SDK 使用者權限，才能使用 SearchVehicles API。詳情請參閱驗證及授權。
使用 SearchVehicles API
如要使用 SearchVehicles API：
- 根據要指派的工作建構
SearchVehiclesRequest。 - 使用建構的要求呼叫
SearchVehiclesAPI (vehicleService.searchVehicles)。 - 處理 API 傳回的
SearchVehicleResponse。
SearchVehiclesRequest 欄位
請使用下列必要屬性欄位建構 SearchVehiclesRequest：
| 欄位 | 說明 |
|---|---|
| parent | 必填。格式須為「provider/{provider}」。提供者必須是 Google Cloud 專案的專案 ID (例如 sample-cloud-project)，且呼叫的服務帳戶所屬的服務帳戶相關聯。 |
| vehicle_types | 必填。要求的車輛類型，可能為 AUTO、TWO_WHEELER、TAXI、TRUCK、BICYCLE 或 PEDESTRIAN。 |
| trip_types | 必填。「專屬」(每位駕駛一次只會有一項有效行程) 或「SHARED」(每位司機一次只會有一或多趟行程)。 |
| minimum_capacity | 必填。新任務的車輛剩餘容量下限 (適用於乘客或配送服務)。 |
| pickup_point | 必填。以經緯度座標表示工作的上車地點。 |
| dropoff_point | 選用設定。工作的下車地點 (以經緯度座標表示)。 如果 Trip_types 包含 TripType.SHARED，則須填寫此欄位。 |
| pickup_radius_meters | 必填。從上車地點出發的車輛搜尋區域半徑，以公尺為單位。 |
| order_by | 必填。透過下列其中一種方式訂購車輛：
|
| 數量 | 必填。從 1 到 50 返回的車輛數量上限。 |
請參閱參考說明文件，查看完整的 SearchVehicleRequestfields。
SearchVehiclesRequest 範例
本節將舉例說明如何建構 SearchVehiclesRequest。
舉例來說，假設您有一項取貨工作，分別在 RestaurantX 和四輛車上指定：
- 車輛 1，距離餐廳 X 3500 公尺。
- 車輛 2，距離 RestaurantX 約 100 公尺，目前提供在地點 A 和 B 上車和下車的行程。
- 車輛 3，距離餐廳 X 200 公尺，其餘的下車地點距離非常遠。
- 車輛 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
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」。 |
搜尋車輛範例
以下範例說明如何使用 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.