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 的車輛。即使一般車輛仍在傳輸位置資訊，也不算過時。如未設定這個欄位，伺服器會使用 5 分鐘做為預設值。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
vehicleTypes[]

object (VehicleType)

必要欄位。將搜尋範圍限制在符合其中一個指定類型的車輛。至少須指定一種交通工具類型。不允許使用類別為 UNKNOWN 的交通工具類型。
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 個必要屬性。這與車輛允許的屬性數量上限相符。
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。

這個篩選函式可做為 AND 子句，但具有其他限制條件，例如 minimumCapacity 或 vehicleTypes。

請注意，只有車輛屬性 (例如 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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
vehiclePickupDistanceMeters

integer

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

integer

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

string (Timestamp format)

完整車輛的行車預計到達時間，前往要求中指定的下車地點。預計到達時間包括在要求中指定的 dropoffPoint 之前的任何路線控點。只有在要求中指定下車地點時，系統才會填入這個值。空白值表示計算預計到達時間時發生錯誤。

RFC3339 世界標準時間「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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

VehicleMatchType

車輛比對類型。

列舉
UNKNOWN 未知的車輛比對類型
EXCLUSIVE 這輛車目前還沒有指定行程，可以繼續前往上車地點。
BACK_TO_BACK 車輛目前已指派給行程，但完成行程後可繼續至上車地點。系統計算預計到達時間和距離時，會將現有行程納入考量。
CARPOOL 車輛的容量足夠，可多人共乘。
CARPOOL_BACK_TO_BACK 車輛會先完成目前進行中的行程，再前往上車地點。系統計算預計到達時間和距離時，會將現有行程納入考量。