Tìm xe

Trong dịch vụ chuyến đi theo yêu cầu của Mobility, bạn có thể tìm thấy các phương tiện ở gần bằng cách sử dụng phương thức SearchVehicles.

Phương thức SearchVehicles cho phép bạn tìm thấy những chiếc xe có sẵn ở gần trong ứng dụng di động dành cho người tiêu dùng phù hợp nhất với một yêu cầu đi xe hoặc giao hàng cụ thể. API SearchVehicles trả về danh sách các xe được xếp hạng có thuộc tính khớp với thuộc tính chuyến đi được yêu cầu. Thứ hạng được sắp xếp theo lựa chọn của bạn về thời gian đến dự kiến, khoảng cách hoặc khoảng cách theo đường thẳng từ điểm đến lấy hàng.

Thuộc tính tìm kiếm Thuộc tính xe
  • Vị trí nhận và trả xe
  • Loại xe và chuyến đi được yêu cầu
  • Dung lượng bắt buộc
  • Các thuộc tính so khớp bắt buộc khác
  • Vị trí xác định gần đây nhất của một xe
  • Trạng thái, loại hoặc sức chứa của xe
  • Các thuộc tính tuỳ chỉnh khác

Sử dụng phương thức SearchVehicles

Để sử dụng SearchVehicles, hãy làm theo quy trình chung sau:

  1. Tạo một SearchVehiclesRequest dựa trên chuyến đi cần chỉ định.
  2. Gọi API SearchVehicles (vehicleService.searchVehicles) bằng yêu cầu đã tạo.
  3. Xử lý SearchVehicleResponse được trả về từ API.

Các trường SearchVehiclesRequest

Sử dụng các trường thuộc tính bắt buộc sau đây để tạo SearchVehiclesRequest:

Trường Mô tả
mẹ Bắt buộc. Phải ở định dạng providers/{provider}. Nhà cung cấp phải là Mã dự án của Dự án Google Cloud mà tài khoản dịch vụ thực hiện lệnh gọi này là thành viên.
vehicle_types Bắt buộc. Loại xe được yêu cầu, có thể là AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE hoặc PEDESTRIAN.
trip_types Bắt buộc. MONO (một chuyến đi đang hoạt động tại mỗi thời điểm cho mỗi tài xế) hoặc SHARED (một hoặc nhiều chuyến đi tại mỗi thời điểm cho mỗi tài xế).
minimum_capacity Bắt buộc. Sức chứa tối thiểu còn lại của xe cho một chuyến đi mới, cho hành khách hoặc giao hàng.
pickup_point Bắt buộc. Vị trí đón khách của chuyến đi theo toạ độ vĩ độ/kinh độ.
dropoff_point Không bắt buộc. Vị trí trả khách của chuyến đi theo toạ độ vĩ độ/kinh độ. Bạn phải điền trường này nếu trip_types chứa TripType.SHARED.
pickup_radius_meters Bắt buộc. Bán kính (tính bằng mét) của khu vực tìm kiếm xe từ điểm đến lấy hàng.
order_by Bắt buộc. Sắp xếp xe theo một trong những cách sau:
  • PICKUP_POINT_ETA, thời gian dự kiến đến điểm đến của xe.
  • PICKUP_POINT_DISTANCE, khoảng cách giữa xe và điểm đón.
  • DROPOFF_POINT_ETA, thời gian dự kiến đến điểm trả khách để hoàn tất chuyến đi.
  • PICKUP_POINT_STRAIGHT_DISTANCE, khoảng cách theo đường thẳng (không phải trên tuyến đường) giữa xe và điểm đón.
số lượng Bắt buộc. Số lượng xe tối đa cần trả về từ 1 đến 50.
Lọc Không bắt buộc. Truy vấn bộ lọc để áp dụng khi tìm kiếm xe.

Hãy tham khảo Tài liệu tham khảo để xem bộ đầy đủ các trường SearchVehicleRequest.

Tình huống SearchVehiclesRequest

Phần này trình bày ví dụ về cách tạo SearchVehiclesRequest.

Ví dụ: giả sử một khách hàng muốn được đón tại Nhà hàng X và bạn có 4 xe:

  • Xe 1: Cách Nhà hàng X 3500m.
  • Xe 2: Cách Nhà hàng X 100 m, đang có một chuyến đi đang hoạt động với điểm đón và trả khách tại vị trí A và B.
  • Xe 3: Cách Nhà hàng X 200 m và còn một điểm trả khách ở rất xa.
  • Xe 4: Cách Nhà hàng X 1.000 m.

Phần sau đây cho thấy nhiều yêu cầu theo loại xe mà chúng trả về.

Trả về Xe 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA
    

Trả về Xe 3 và 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled
    

Trả về Xe 2, 3 và 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL
    

Các trường SearchVehiclesResponse

SearchVehiclesResponse bao gồm danh sách các thực thể VehicleMatch, được xếp hạng theo thuộc tính order_by được chỉ định trong SearchVehiclesRequest. Mỗi thực thể VehicleMatch có các trường sau:

Trường Mô tả
xe cộ Đối tượng Vehicle, bao gồm cả thuộc tính vehicle_id và Vehicle.
vehicle_pickup_eta Giờ đến dự kiến của xe tại vị trí đón khách của chuyến đi mới. Đây là thời gian đến dự kiến khi lái xe.
vehicle_pickup_distance_meter Khoảng cách tính bằng mét giữa xe và vị trí đến lấy hàng của chuyến đi mới.
vehicle_pickup_straight_line_distance_meter Khoảng cách theo đường thẳng tính bằng mét giữa xe và vị trí đến lấy hàng của chuyến đi mới.
vehicle_dropoff_eta Dấu thời gian của thời gian đến dự kiến của xe tại vị trí đến lấy hàng của chuyến đi mới. Xin lưu ý rằng giờ đến dự kiến là giờ đến dự kiến khi lái xe.
vehicle_trips_waypoints Danh sách các điểm trung gian còn lại, bao gồm cả điểm đón và điểm trả khách, cho các chuyến đi đang hoạt động hiện được chỉ định cho xe.
vehicle_match_type Loại chuyến đi của xe, có thể là EXCLUSIVE, BACK_TO_BACK, CARPOOL hoặc CARPOOL_BACK_TO_BACK.

Để biết danh sách đầy đủ các trường VehicleMatch, hãy xem:

Sử dụng truy vấn bộ lọc

SearchVehiclesListVehicles hỗ trợ lọc theo các thuộc tính xe bằng cách sử dụng cụm từ tìm kiếm bộ lọc.

Truy vấn bộ lọc CHỈ hỗ trợ lọc theo thuộc tính tuỳ chỉnh cho xe và không thể dùng cho các trường khác. Khi được sử dụng trong một lượt tìm kiếm có các tiêu chí khác về trường, chẳng hạn như minimum_capacity hoặc vehicle_types, truy vấn bộ lọc sẽ hoạt động như một mệnh đề AND.

Ví dụ: nếu bạn tìm kiếm một chiếc xe có sức chứa tối thiểu là 6 người và lọc một attributes như cho phép mang theo thú cưng, thì tiêu chí của bạn sẽ chỉ trả về những chiếc xe vừa cho phép mang theo thú cưng vừa có thể chở ít nhất 6 người.

Để biết cú pháp truy vấn bộ lọc, hãy xem AIP-160 để biết ví dụ. Để biết thông tin chi tiết về cách tạo thuộc tính xe, hãy xem Trường thuộc tính xe trong hướng dẫn Cập nhật các trường xe.

Ví dụ về SearchVehicles

Ví dụ sau đây minh hoạ cách sử dụng API SearchVehicles bằng thư viện gRPC Java.

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.

Bước tiếp theo