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미터 이상 10000미터 이하여야 합니다.
count

integer

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

integer

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

enum (TripType)

필수 항목입니다. 제안된 경로의 유형을 나타냅니다. 정확히 1개의 유형을 포함해야 합니다. 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 연산입니다. requiredAttributes는 최대 50개까지 허용됩니다. 차량에 허용되는 최대 속성 수와 일치합니다.
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)

요청에 지정된 수령 지점까지 차량의 도착 예정 시간입니다. 값이 비어 있으면 차량의 도착 예정 시간 계산에 실패했음을 나타냅니다. 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)

도착 예상 시간을 계산하는 데 사용되는 경유지의 순서가 지정된 목록입니다. 이 목록에는 차량 위치, 차량이 활성화된 이동의 승차 지점, 요청에 제공된 승차 지점이 포함됩니다. 빈 목록은 차량의 도착 예정 시간 계산에 실패했음을 나타냅니다.
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 차량은 현재 진행 중인 이동을 완료한 후 픽업 장소로 이동합니다. 도착예정시간과 거리를 계산할 때 기존 이동이 고려됩니다.