Tìm xe

Trong dịch vụ di chuyển theo yêu cầu về di chuyển, bạn có thể tìm thấy các xe ở 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 các xe hiện có ở 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 chuyến đi hoặc dịch vụ giao hàng cụ thể của bạn. API SearchVehicles trả về một danh sách xếp hạng các xe có khớp với các 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 giờ đến dự kiến, khoảng cách hoặc khoảng cách theo đường thẳng từ điểm đón.

Tìm kiếm thuộc tính	Thuộc tính xe
Địa điểm 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 chiếc 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

Lưu ý: Bạn phải có Người dùng SDK người tiêu dùng hoặc Quản trị viên theo yêu cầu của Fleet Engine để sử dụng API SearchVehicles. Để biết thêm thông tin, hãy xem Các vai trò trong tài khoản dịch vụ của Fleet Engine.

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 SearchVehiclesRequest dựa trên chuyến đi sẽ được chỉ định.
2. Gọi API SearchVehicles (vehicleService.searchVehicles) bằng tạo sẵn.
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 để tạo SearchVehiclesRequest:

Trường	Mô tả
mẹ	Bắt buộc. Phải ở định dạng nhà cung cấp/{provider}. Nhà cung cấp phải là Mã dự án của dự án trên Google Cloud mà tài khoản dịch vụ thực hiện cuộc gọi này là thành viên.
vehicle_types	Bắt buộc. Các loại phương tiện được yêu cầu: XE Ô TÔ, HAI_WHEELER, TAXI, XE TẢI, XE ĐẠP hoặc Xe ĐI BỘ.
trip_types	Bắt buộc. ĐỘC QUYỀN (một chuyến đi đang hoạt động tại một thời điểm cho mỗi tài xế) hoặc CHIA SẺ (một hoặc nhiều chuyến đi cùng một lúc 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 trong chuyến đi mới, dành cho hành khách hoặc hàng giao.
pickup_point	Bắt buộc. Vị trí đón 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 độ. Đây là trường bắt buộc nếu Trip_types chứa TripType.SHARED.
pickup_radius_meters	Bắt buộc. Bán kính tính theo mét của khu vực tìm xe tính từ điểm đón.
order_by	Bắt buộc. Đặt mua xe theo một trong những cách sau: PICKUP_POINT_ETA, giờ đến dự kiến của xe tại điểm đón. PICKUP_POINT_DISTANCE, khoảng cách giữa xe và điểm đón. DROPOFF_POINT_ETA, giờ đến dự kiến của xe để hoàn tất chuyến đi tại điểm trả khách. PICKUP_POINT_STRAIGHT_DISTANCE, khoảng cách theo đường thẳng (không nằm trong 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 phép quay về từ 1 đến 50.
Lọc	Không bắt buộc. Một cụm từ tìm kiếm để áp dụng khi tìm kiếm xe.

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

Tình huống SearchvehiclesRequest

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

Ví dụ: Giả sử một khách hàng muốn đến lấy hàng tại RestaurantX, và bạn có 4 xe:

• Xe 1: Cách RestaurantX 3500 m.
• Xe 2: Cách RestaurantX 100 m, trong đó có một chuyến đi đang diễn ra và có dịch vụ đến lấy hàng và trả khách tại địa điểm A và B.
• Xe 3: cách RestaurantX 200 m, còn lại một trạm dừng chân ở rất xa.
• Xe 4: Cách RestaurantX 1000m.

Phần sau đây cho thấy nhiều yêu cầu theo chiếc xe mà khách hàng trả lại.

Trả lại 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

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

Trường	Mô tả
xe cộ	Đối tượng Vehicle, bao gồm cả các thuộc tính xe_id và Vehicle.
vehicle_pickup_eta	Giờ đến dự kiến của xe tại vị trí đón 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 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 của chuyến đi mới.
vehicle_dropoff_eta	Dấu thời gian thời gian đến dự kiến của xe tại vị trí đón trong chuyến đi mới. Xin lưu ý rằng ETA là thời gian đến với hoạt động lái xe.
vehicle_trips_waypoints	Danh sách các điểm tham chiếu còn lại, bao gồm cả điểm đón và 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: EXCLUSIVE, BACK_TO_BACK, CARPOOL hoặc CARPOOL_BACK_TO_BACK.

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

• VehicleMatch message (gRPC)
• VehicleMatch resource (REST)

Lưu ý: Xe phải trực tuyến (với xe_state=online) thì xe mới có thể tìm kiếm được và được SearchVehicles trả về.

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

Chế độ lọc hỗ trợ SearchVehicles và ListVehicles cho các thuộc tính của xe bằng cách sử dụng truy vấn bộ lọc.

Cụm từ tìm kiếm về bộ lọc CHỈ hỗ trợ tính năng lọc thuộc tính tuỳ chỉnh cho xe, và Không thể sử dụng cho các trường khác. Khi được dùng trong nội dung tìm kiếm bao gồm trường khác tiêu chí, chẳng hạn như minimum_capacity hoặc vehicle_types, truy vấn lọc có hàm dưới dạng 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 và lọc attributes, chẳng hạn như thân thiện với thú cưng, tiêu chí của bạn sẽ chỉ trả về những xe phù hợp với thú cưng và có thể chở ít nhất 6 hành khách.

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

Lưu ý: Tốt nhất là bạn nên tránh sử dụng các trường thuộc tính sau đây khi đưa ra một truy vấn bộ lọc: required_attributes, required_one_of_attributes hoặc required_one_of_attributes_sets. Thay vào đó, hãy sử dụng trường filter sẽ thay thế các trường đó. Ngoài ra, bạn sẽ nhận được thông báo lỗi nếu yêu cầu chỉ định một giá trị trong cả trường filter và thuộc tính còn lại các trường khác.

Ví dụ về Searchvehicles

Ví dụ sau đây trình bày cách dùng API SearchVehicles trong Thư viện Java gRPC.

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.

Các bước tiếp theo

• Tạo chuyến đi theo yêu cầu