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 到 10,000 米之间（包括这两个数值）。
count

integer

必需。指定要返回的车辆数量上限。该值必须介于 1 到 50 之间（包括这两个数值）。
minimumCapacity

integer

必需。指定要考虑的乘客人数。此值必须大于或等于 1。载客量值不计入驾驶员。
tripTypes[]

enum (TripType)

必需。表示建议的行程类型。必须只包含一种类型。不允许使用 UNKNOWN_TRIP_TYPE。将搜索范围限制为仅包含可支持相应行程类型的车辆。
maximumStaleness

string (Duration format)

将搜索范围限制为仅包含在指定时段内向 Fleet Engine 发送过位置信息更新的车辆。仍在传输位置信息的静态车辆不会被视为已过时。如果未设置此字段，服务器会将 5 分钟用作默认值。

该时长以秒为单位，最多包含九个小数位，以“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 中的包含性析取/或运算，也是 VehicleAttributeList 集合中的联接/与运算。
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，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
vehiclePickupDistanceMeters

integer

车辆当前位置与请求中指定的上车点之间的距离，包括现有行程的任何中途上车点或下车点。此距离包括计算出的驾车（路线）距离，以及导航终点和请求的上车点之间的直线距离。（导航终点与请求的接人点之间的距离通常很短。）如果出现空值，则表示计算距离时出错。
vehiclePickupStraightLineDistanceMeters

integer

必需。车辆与请求中指定的上车点之间的直线距离。
vehicleDropoffEta

string (Timestamp format)

车辆到达请求中指定的下车点的完整预计到达时间 (ETA)。预计到达时间包括在请求中指定的 dropoffPoint 之前在任何航点停靠的时间。只有在请求中指定了下车点时，系统才会填充此值。如果值为空，则表示计算预计到达时间时出错。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："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。
orderedBy

enum (VehicleMatchOrder)

请求用于对车辆匹配进行排序的顺序。等同于 requestedOrderedBy。

关键点

描述 SearchVehiclesResponse 中 VehicleMatch 路线上的中间点。在所有其他端点中，此概念表示为 TripWaypoint。

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

object (LatLng)

此航点的位置。
eta

string (Timestamp format)

车辆到达此航点的预计时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

VehicleMatchType

车辆匹配类型。

枚举
UNKNOWN 未知车辆匹配类型
EXCLUSIVE 车辆目前没有分配任何行程，可以继续前往上车点。
BACK_TO_BACK 车辆目前已分配到某个行程，但可以在完成正在进行的行程后前往上车点。计算预计到达时间和距离时会将现有行程考虑在内。
CARPOOL 车辆载客量足够，可以提供拼车服务。
CARPOOL_BACK_TO_BACK 车辆会先完成当前正在进行的行程，然后再前往上车点。计算预计到达时间和距离时会将现有行程考虑在内。