Method: providers.vehicles.search

傳回符合要求選項的車輛清單。

HTTP 要求

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

這個網址使用 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)

必要欄位。代表建議行程的類型。必須包含一個類型。不允許 UNKNOWN_TRIP_TYPE。將搜尋範圍限制在可支援該行程類型的車輛。
maximumStaleness

string (Duration format)

將搜尋範圍限制在指定時間範圍內，只搜尋已向 Fleet Engine 傳送位置更新的車輛。靜止車輛仍會傳送位置，因此不會被視為過時。如果未設定這個欄位，伺服器會使用五分鐘做為預設值。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
vehicleTypes[]

object (VehicleType)

必要欄位。將搜尋範圍限制在某個指定類型的車輛。您必須指定至少一種車輛類型。不允許類別為 UNKNOWN 的 VehicleTypes。
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)

車輛行駛至要求中指定的接送地點所需的預估時間。空值表示無法計算車輛的預估到達時間。如果 SearchVehiclesRequest.include_back_to_back 為 true，且這輛車有正在進行的行程，vehiclePickupEta 就會包含完成目前行程所需的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 規格化，並使用 0、3、6 或 9 小數位數。系統也接受「Z」以外的偏移值。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
vehiclePickupDistanceMeters

integer

車輛目前所在位置與要求中指定上車地點的距離，包括現有行程的任何中途上車或下車地點。這個距離包含計算出的行車 (路線) 距離，以及導航終點和要求的接送點之間的直線距離。(導航終點和要求的接送點之間的距離通常很短)。空值表示計算距離時發生錯誤。
vehiclePickupStraightLineDistanceMeters

integer

必要欄位。車輛與要求中指定的接送地點之間的直線距離。
vehicleDropoffEta

string (Timestamp format)

車輛從要求中指定的下車地點出發，到達目的地的預估車程時間。預估抵達時間會將在要求中指定的 dropoffPoint 前停靠任何路線控點的時間納入計算。只有在要求中指定了下車點時，系統才會填入這個值。空值表示計算預估到達時間時發生錯誤。

使用 RFC 3339，產生的輸出內容一律會經過 Z 規格化，並使用 0、3、6 或 9 小數位數。系統也接受「Z」以外的偏移值。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
vehiclePickupToDropoffDistanceMeters

integer

車輛從要求中指定的接送點到下車點的駕駛距離 (以公尺為單位)。距離只計算兩個點之間的距離，不包括車輛前往上車/下車地點前必須經過的車輛位置或任何其他點。只有在請求中指定 dropoffPoint 時，系統才會填入這個值。空值表示無法計算從要求中指定的接送地點到下車地點的距離。
tripType

enum (TripType)

必要欄位。用於計算上車地點預估抵達時間的請求行程類型。
vehicleTripsWaypoints[]

object (Waypoint)

用於計算預估到達時間的定點排序清單。清單包含車輛位置、車輛有效行程的接送地點，以及要求中提供的接送地點。如果清單為空白，表示無法計算車輛的預估抵達時間。
vehicleMatchType

enum (VehicleMatchType)

車輛比對類型。
requestedOrderedBy

enum (VehicleMatchOrder)

請求的車輛比對排序順序。等同於 orderedBy。
orderedBy

enum (VehicleMatchOrder)

請求的車輛比對排序順序。等同於 requestedOrderedBy。

途經點

說明 SearchVehiclesResponse 中 VehicleMatch 路線的中間點。在所有其他端點中，這個概念會以 TripWaypoint 表示。

JSON 表示法 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
欄位
latLng

object (LatLng)

此航點的位置。
eta

string (Timestamp format)

車輛抵達這個路標點的預估時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 規格化，並使用 0、3、6 或 9 小數位數。系統也接受「Z」以外的偏移值。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

VehicleMatchType

車輛比對類型。

列舉
UNKNOWN 不明的車輛比對類型
EXCLUSIVE 車輛目前沒有指派的行程，可以繼續前往上車地點。
BACK_TO_BACK 車輛目前已指派給行程，但完成行程後，可繼續前往上車地點。預估抵達時間和距離計算會考量現有行程。
CARPOOL 車輛有足夠的空間可供共乘。
CARPOOL_BACK_TO_BACK 車輛會先完成目前的有效行程，再前往上車地點。預估抵達時間和距離計算會考量現有行程。