Method: providers.vehicles.search

요청 옵션과 일치하는 차량 목록을 반환합니다.

HTTP 요청

POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search

URL은 gRPC 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
parent

string

필수 항목입니다. providers/{provider} 형식이어야 합니다. 제공업체는 이 호출을 실행하는 서비스 계정이 구성원인 Google Cloud 프로젝트의 프로젝트 ID (예: sample-cloud-project)여야 합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "header": {
    object (RequestHeader)
  },
  "pickupPoint": {
    object (TerminalLocation)
  },
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "pickupRadiusMeters": integer,
  "count": integer,
  "minimumCapacity": integer,
  "tripTypes": [
    enum (TripType)
  ],
  "maximumStaleness": string,
  "vehicleTypes": [
    {
      object (VehicleType)
    }
  ],
  "requiredAttributes": [
    {
      object (VehicleAttribute)
    }
  ],
  "requiredOneOfAttributes": [
    {
      object (VehicleAttributeList)
    }
  ],
  "requiredOneOfAttributeSets": [
    {
      object (VehicleAttributeList)
    }
  ],
  "orderBy": enum (VehicleMatchOrder),
  "includeBackToBack": boolean,
  "tripId": string,
  "currentTripsPresent": enum (CurrentTripsPresent),
  "filter": string
}
입력란
header

object (RequestHeader)

표준 Fleet Engine 요청 헤더입니다.
pickupPoint

object (TerminalLocation)

필수 항목입니다. 검색할 승차 지점입니다.
dropoffPoint

object (TerminalLocation)

고객이 원하는 하차 위치입니다. tripTypes에 TripType.SHARED이 포함된 경우 이 필드는 필수입니다.
pickupRadiusMeters

integer

필수 항목입니다. 승차 지점 주변의 차량 검색 반경을 정의합니다. 검색 반경 내의 차량만 반환됩니다. 값은 400~10,000미터 (포함) 사이여야 합니다.
count

integer

필수 항목입니다. 반납할 최대 차량 수를 지정합니다. 값은 1 이상 50 이하여야 합니다.
minimumCapacity

integer

필수 항목입니다. 이동을 위해 고려 중인 승객 수를 지정합니다. 값은 1 이상이어야 합니다. 드라이버는 용량 값에 고려되지 않습니다.
tripTypes[]

enum (TripType)

필수 항목입니다. 제안된 이동의 유형을 나타냅니다. 정확히 하나의 유형을 포함해야 합니다. UNKNOWN_TRIP_TYPE은(는) 허용되지 않습니다. 해당 이동 유형을 지원할 수 있는 차량으로 검색을 제한합니다.
maximumStaleness

string (Duration format)

지정된 기간 내에 Fleet Engine으로 위치 업데이트를 전송한 차량으로 검색을 제한합니다. 여전히 위치를 전송하고 있는 정차 차량은 오래된 것으로 간주되지 않습니다. 이 필드가 설정되지 않으면 서버는 기본값으로 5분을 사용합니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
vehicleTypes[]

object (VehicleType)

필수 항목입니다. 지정된 유형 중 하나가 있는 차량으로 검색을 제한합니다. 차량 유형을 하나 이상 지정해야 합니다. UNKNOWN 카테고리의 VehicleType은 허용되지 않습니다.
requiredAttributes[]

object (VehicleAttribute)

호출자는 requiredAttributes, requiredOneOfAttributes, requiredOneOfAttributeSets 필드의 조합을 사용하여 복잡한 논리 연산을 구성할 수 있습니다.

requiredAttributes는 목록입니다. requiredOneOfAttributes는 목록 목록을 허용하는 메시지를 사용합니다. 두 필드를 함께 사용하면 다음 표현식을 구성할 수 있습니다.

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(requiredOneOfAttributes[0][0] OR requiredOneOfAttributes[0][1] OR
...)
AND
(requiredOneOfAttributes[1][0] OR requiredOneOfAttributes[1][1] OR
...)

지정된 속성이 있는 차량으로만 검색을 제한합니다. 이 필드는 결합/AND 연산입니다. 최대 50개의 requiredAttributes가 허용됩니다. 이는 차량에 허용되는 최대 속성 수와 일치합니다.
requiredOneOfAttributes[]

object (VehicleAttributeList)

각 VehicleAttributeList에 지정된 속성 중 하나 이상이 있는 차량으로 검색을 제한합니다. 각 목록 내에서 차량은 속성 중 하나 이상과 일치해야 합니다. 이 필드는 각 VehicleAttributeList의 포괄적 분리/OR 연산과 VehicleAttributeList 컬렉션 전반의 결합/AND 연산입니다.
requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets는 추가 기능을 제공합니다.

requiredOneOfAttributes와 마찬가지로 requiredOneOfAttributeSets는 목록 목록을 허용하는 메시지를 사용하여 다음과 같은 표현식을 허용합니다.

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(
  (requiredOneOfAttributeSets[0][0] AND
  requiredOneOfAttributeSets[0][1] AND
  ...)
  OR
  (requiredOneOfAttributeSets[1][0] AND
  requiredOneOfAttributeSets[1][1] AND
  ...)
)

VehicleAttributeList에 모든 속성이 있는 차량으로만 검색을 제한합니다. 각 목록 내에서 차량은 모든 속성과 일치해야 합니다. 이 필드는 각 VehicleAttributeList의 결합/AND 연산과 VehicleAttributeList 컬렉션 전반의 포괄적 분리/OR 연산입니다.
orderBy

enum (VehicleMatchOrder)

필수 항목입니다. 결과에 원하는 정렬 기준을 지정합니다.
includeBackToBack

boolean

하나의 이동이 활성화된 차량이 이 검색에 해당하는지를 나타냅니다. 이 필드는 currentTripsPresent가 지정되지 않은 경우에만 사용됩니다. currentTripsPresent이 지정되지 않고 이 필드가 false이면 할당된 이동이 있는 차량이 검색결과에서 제외됩니다. currentTripsPresent가 지정되지 않고 이 필드가 true이면 검색결과에 ENROUTE_TO_DROPOFF 상태의 활성 이동이 있는 차량이 포함될 수 있습니다. currentTripsPresent가 지정되면 이 필드를 true로 설정할 수 없습니다.

기본값은 false입니다.
tripId

string

이 SearchVehicleRequest와 연결된 이동을 나타냅니다.
currentTripsPresent

enum (CurrentTripsPresent)

이동이 활성화된 차량이 이 검색에 표시될 수 있는지 여부를 나타냅니다. tripType에 SHARED가 포함된 경우 CURRENT_TRIPS_PRESENT_UNSPECIFIED 이외의 값으로 설정해야 합니다.
filter

string

선택사항입니다. 차량을 검색할 때 적용할 필터 쿼리입니다. 필터 구문의 예는 http://aip.dev/160을 참고하세요.

이 필드는 requiredAttributes, requiredOneOfAttributes, required_one_of_attributes_sets 필드를 대체하도록 설계되었습니다. 여기에 비어 있지 않은 값이 지정되어 있으면 requiredAttributes, requiredOneOfAttributes, required_one_of_attributes_sets 필드는 비어 있어야 합니다.

이 필터는 minimumCapacity 또는 vehicleTypes와 같은 다른 제약 조건이 있는 AND 절로 작동합니다.

지원되는 유일한 쿼리는 차량 속성 (예: attributes.<key> = <value> 또는 attributes.<key1> = <value1> AND attributes.<key2> = <value2>)입니다. 필터 쿼리에 허용되는 최대 제한사항 수는 50개입니다.

또한 모든 속성은 문자열로 저장되므로 속성에 대해 지원되는 비교는 문자열 비교뿐입니다. 숫자 또는 불리언 값과 비교하려면 값을 명시적으로 따옴표로 묶어 문자열로 처리해야 합니다 (예: attributes.<key> = "10" 또는 attributes.<key> = "true").

응답 본문

vehicles.search 응답 메시지입니다.

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
입력란
matches[]

object (VehicleMatch)

SearchVehiclesRequest 기준과 일치하는 차량 목록으로, SearchVehiclesRequest.order_by 필드에 따라 정렬됩니다.

VehicleAttributeList

차량 속성의 목록 목록 데이터 유형입니다.

JSON 표현 
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
입력란
attributes[]

object (VehicleAttribute)

이 컬렉션의 속성 목록입니다.

VehicleMatchOrder

응답에서 차량 일치 순서를 지정합니다.

열거형
UNKNOWN_VEHICLE_MATCH_ORDER 지정되지 않거나 인식할 수 없는 차량과 일치하는 주문에 사용되는 기본값입니다.
PICKUP_POINT_ETA 승차 지점까지 차량 운전 시간을 기준으로 오름차순으로 정렬합니다.
PICKUP_POINT_DISTANCE 승차 지점까지 차량 운전 거리별 오름차순의 순서입니다.
DROPOFF_POINT_ETA 하차 지점까지 차량 운전 시간에 따라 오름차순으로 정렬합니다. 이 주문은 요청에 하차 지점이 지정된 경우에만 사용할 수 있습니다.
PICKUP_POINT_STRAIGHT_DISTANCE 차량이 마지막으로 보고된 위치에서 승차 지점까지 직선 거리를 기준으로 한 오름차순 정렬입니다.
COST 구성된 일치 비용에 따른 오름차순 정렬입니다. 일치 비용은 직선 거리와 도착예정시간 사이의 가중치 계산값으로 정의됩니다. 가중치는 기본값으로 설정되며 고객별로 수정할 수 있습니다. 프로젝트에서 이러한 가중치를 수정해야 하는 경우 Google 지원팀에 문의하세요.

CurrentTripsPresent

차량의 현재 이동에 대한 제한사항 유형을 지정합니다.

열거형
CURRENT_TRIPS_PRESENT_UNSPECIFIED 이동이 있는 차량의 이용 가능 여부는 includeBackToBack 필드에 따라 결정됩니다.
NONE 경로가 없는 차량은 검색결과에 표시될 수 있습니다. 이 값을 사용할 때는 includeBackToBack가 true일 수 없습니다.
ANY 현재 경로가 최대 5개이고 경유지가 10개 이하인 차량이 검색결과에 포함됩니다. 이 값을 사용할 때는 includeBackToBack가 true일 수 없습니다.

VehicleMatch

차량 SearchVehiclesRequest의 활성 이동 지점과 일치하는 차량 및 관련 추정치가 포함됩니다.

JSON 표현 
{
  "vehicle": {
    object (Vehicle)
  },
  "vehiclePickupEta": string,
  "vehiclePickupDistanceMeters": integer,
  "vehiclePickupStraightLineDistanceMeters": integer,
  "vehicleDropoffEta": string,
  "vehiclePickupToDropoffDistanceMeters": integer,
  "tripType": enum (TripType),
  "vehicleTripsWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "vehicleMatchType": enum (VehicleMatchType),
  "requestedOrderedBy": enum (VehicleMatchOrder),
  "orderedBy": enum (VehicleMatchOrder)
}
입력란
vehicle

object (Vehicle)

필수 항목입니다. 요청과 일치하는 차량입니다.
vehiclePickupEta

string (Timestamp format)

요청에 지정된 승차 지점까지 차량의 운전 도착예정시간입니다. 값이 비어 있으면 차량의 ETA 계산에 실패했음을 나타냅니다. SearchVehiclesRequest.include_back_to_back이(가) true이고 이 차량에 진행 중인 이동이 있는 경우 vehiclePickupEta에는 현재 진행 중인 이동을 완료하는 데 필요한 시간이 포함됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
vehiclePickupDistanceMeters

integer

차량의 현재 위치에서 요청에 지정된 승차 지점까지의 거리입니다. 기존 이동의 중간 승차 또는 하차 지점도 포함됩니다. 이 거리는 계산된 운전 (경로) 거리, 내비게이션 종료 지점과 요청된 승차 지점 사이의 직선 거리로 구성됩니다. 내비게이션 종료 지점과 요청된 승차 지점 사이의 거리는 일반적으로 작습니다. 값이 비어 있으면 거리 계산 시 오류가 있음을 나타냅니다.
vehiclePickupStraightLineDistanceMeters

integer

필수 항목입니다. 요청에 지정된 차량과 승차 지점 사이의 직선 거리입니다.
vehicleDropoffEta

string (Timestamp format)

요청에 지정된 하차 지점까지 전체 차량의 운전 도착예정시간입니다. ETA에는 요청에 지정된 dropoffPoint 전에 경유지에 정차하는 시간이 포함됩니다. 요청에 하차 지점이 지정된 경우에만 값이 채워집니다. 빈 값은 ETA를 계산하는 오류를 나타냅니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
vehiclePickupToDropoffDistanceMeters

integer

승차 지점에서 요청에 지정된 하차 지점까지의 차량 운전 거리 (미터)입니다. 거리는 두 지점 사이의 유일한 값이며, 차량 위치 또는 차량이 승차 지점 또는 하차 지점을 방문하기 전에 방문해야 하는 다른 지점은 포함되지 않습니다. 이 값은 요청에 dropoffPoint가 지정된 경우에만 채워집니다. 값이 비어 있으면 요청에 지정된 승차 지점에서 하차 지점까지의 거리를 계산하지 못했음을 나타냅니다.
tripType

enum (TripType)

필수 항목입니다. 승차 지점까지의 도착예정시간을 계산하는 데 사용된 요청의 이동 유형입니다.
vehicleTripsWaypoints[]

object (Waypoint)

도착예정시간을 계산하는 데 사용되는 경유지의 순서가 지정된 목록입니다. 이 목록에는 차량 위치, 진행 중인 차량 픽업 지점, 요청에 제공된 승차 지점이 포함됩니다. 빈 목록은 차량의 ETA 계산에 실패했음을 나타냅니다.
vehicleMatchType

enum (VehicleMatchType)

일치하는 차량 유형입니다.
requestedOrderedBy

enum (VehicleMatchOrder)

차량 일치 항목 정렬에 요청된 주문입니다.
orderedBy

enum (VehicleMatchOrder)

이 차량에 사용된 실제 주문입니다. 일반적으로 요청의 'orderBy' 필드와 일치하지만 내부 서버 오류와 같은 특정 상황에서는 다른 메서드를 사용할 수 있습니다 (예: PICKUP_POINT_STRAIGHT_DISTANCE).

경유지

SearchVehiclesResponse의 VehicleMatch 경로에 있는 중간 지점을 설명합니다. 이 개념은 다른 모든 엔드포인트에서 TripWaypoint로 표현됩니다.

JSON 표현 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
입력란
latLng

object (LatLng)

이 경유지의 위치입니다.
eta

string (Timestamp format)

차량이 이 경유지에 도착하는 예상 시간입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.

VehicleMatchType

차량 일치 유형입니다.

열거형
UNKNOWN 알 수 없는 차량 검색 유형
EXCLUSIVE 차량에 현재 지정된 이동이 없으며 승차 지점으로 이동할 수 있습니다.
BACK_TO_BACK 차량이 현재 이동에 지정되어 있지만 진행 중인 이동을 완료한 후 승차 지점으로 이동할 수 있습니다. 도착예정시간과 거리 계산 시 기존 이동경로를 고려합니다.
CARPOOL 차량에 탑승하기에 충분한 승차임이 있습니다.
CARPOOL_BACK_TO_BACK 차량이 승차 지점으로 이동하기 전에 현재 진행 중인 이동을 완료합니다. 도착예정시간과 거리 계산 시 기존 이동경로를 고려합니다.