차량 검색

모빌리티 온디맨드 이동 경로 서비스의 일부로 SearchVehicles 메서드를 사용하여 주변 차량을 찾을 수 있습니다.

SearchVehicles 메서드를 사용하면 특정 차량 또는 배송 요청에 가장 적합한 소비자 모바일 앱에서 사용 가능한 주변 차량을 찾을 수 있습니다. SearchVehicles API는 요청된 이동 경로 속성과 일치하는 속성을 가진 차량의 순위가 지정된 목록을 반환합니다. 순위는 승차 지점으로부터의 예상 도착 시간, 거리 또는 직선 거리 중에서 선택한 항목을 기준으로 정렬됩니다.

속성 검색	차량 속성
승차 및 하차 위치 요청된 차량 및 이동 경로 유형 필요한 용량 기타 필수 일치 속성	차량의 마지막으로 알려진 위치 차량 상태, 유형 또는 용량 기타 맞춤 속성

`SearchVehicles` 메서드 사용

SearchVehicles를 사용하려면 다음 일반적인 절차를 따르세요.

할당할 이동 경로를 기반으로 SearchVehiclesRequest를 구성합니다.
구성된 요청으로 SearchVehicles API (vehicleService.searchVehicles)를 호출합니다.
API에서 반환된 SearchVehicleResponse를 처리합니다.

SearchVehiclesRequest 필드

다음 필수 속성 필드를 사용하여 SearchVehiclesRequest를 구성합니다.

필드	설명
parent	필수. providers/{provider} 형식이어야 합니다. 제공업체는 이 호출을 실행하는 서비스 계정이 속한 Google Cloud 프로젝트의 프로젝트 ID여야 합니다.
vehicle_types	필수. 요청된 차량 유형(AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE 또는 PEDESTRIAN)입니다.
trip_types	필수. EXCLUSIVE (운전자당 한 번에 하나의 활성 이동 경로) 또는 SHARED (운전자당 한 번에 하나 이상의 이동 경로)입니다.
minimum_capacity	필수. 새 이동 경로의 최소 남은 차량 용량(승객 또는 배송)입니다.
pickup_point	필수. 위도/경도 좌표의 이동 경로 승차 위치입니다.
dropoff_point	선택사항입니다. 위도/경도 좌표의 이동 경로 하차 위치입니다. trip_types에 TripType.SHARED가 포함된 경우 이 필드는 필수입니다.
pickup_radius_meters	필수. 승차 지점으로부터 차량 검색 영역의 반경(미터)입니다.
order_by	필수. 다음 중 하나로 차량을 정렬합니다. PICKUP_POINT_ETA: 승차 지점에서의 차량 예상 도착 시간입니다. PICKUP_POINT_DISTANCE: 차량과 승차 지점 간의 거리입니다. DROPOFF_POINT_ETA: 하차 지점에서 이동 경로를 완료하기 위한 차량의 예상 도착 시간입니다. PICKUP_POINT_STRAIGHT_DISTANCE: 차량과 승차 지점 간의 직선 거리 (경로에 없음)입니다.
count	필수. 반환할 최대 차량 수(1~50)입니다.
filter	선택사항. 차량을 검색할 때 적용할 필터 쿼리입니다.
maximum_staleness	선택사항. 지정된 기간 내에 Fleet Engine에 위치 업데이트를 전송한 차량만 검색하도록 제한합니다. 이 필드가 설정되지 않으면 서버에서 5분을 기본값으로 사용합니다.

SearchVehicleRequest 필드의 전체 집합은 참조 문서를 참고하세요. SearchVehicleRequest

SearchVehiclesRequest 시나리오

이 섹션에서는 SearchVehiclesRequest를 구성하는 방법을 보여주는 예를 제공합니다.

예를 들어 고객이 RestaurantX에서 승차하기를 원하고 차량이 4대 있다고 가정해 보겠습니다.

차량 1: RestaurantX에서 3,500m 떨어져 있습니다.
차량 2: RestaurantX에서 100m 떨어져 있으며 위치 A와 B에서 승차 및 하차하는 활성 이동 경로가 있습니다.
차량 3: RestaurantX에서 200m 떨어져 있으며 하차 지점이 하나 남아 있는데 매우 멀리 떨어져 있습니다.
차량 4: RestaurantX에서 1,000m 떨어져 있습니다.

다음은 반환하는 차량별로 다양한 요청을 보여줍니다.

차량 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

차량 2, 3, 4 반환

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

SearchVehiclesResponse 필드

SearchVehiclesResponse는 SearchVehiclesRequest에서 지정된 order_by 속성을 기준으로 순위가 지정된 VehicleMatch 항목 목록으로 구성됩니다. 각 VehicleMatch 항목에는 다음 필드가 있습니다.

필드	설명
vehicle	vehicle_id 및 `Vehicle` 속성을 포함한 `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 예

다음 예에서는 SearchVehicles API를 사용하여 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.

다음 단계

DeleteVehicle