Method: providers.vehicles.search

Trả về danh sách xe phù hợp với các lựa chọn trong yêu cầu.

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Thông số
parent

string

Bắt buộc. Phải ở định dạng providers/{provider}. Nhà cung cấp phải là Mã dự án (ví dụ: sample-cloud-project) của dự án trên Google Cloud mà tài khoản dịch vụ thực hiện lệnh gọi này là thành viên.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng 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
}
Trường
header

object (RequestHeader)

Tiêu đề tiêu chuẩn của yêu cầu Fleet Engine.
pickupPoint

object (TerminalLocation)

Bắt buộc. Điểm đón để tìm kiếm ở gần.
dropoffPoint

object (TerminalLocation)

Vị trí trả xe dự kiến của khách hàng. Đây là trường bắt buộc nếu tripTypes chứa TripType.SHARED.
pickupRadiusMeters

integer

Bắt buộc. Xác định bán kính tìm kiếm xe xung quanh điểm nhận hàng. Chúng tôi chỉ trả lại những phương tiện trong phạm vi bán kính tìm kiếm. Giá trị phải nằm trong khoảng từ 400 đến 10.000 mét (bao gồm).
count

integer

Bắt buộc. Cho biết số lượng xe tối đa cần trả về. Giá trị phải nằm trong khoảng từ 1 đến 50 (bao gồm).
minimumCapacity

integer

Bắt buộc. Xác định số lượng hành khách được xem xét cho một chuyến đi. Giá trị này phải lớn hơn hoặc bằng 1. Người lái xe không được xem xét trong giá trị hạn mức.
tripTypes[]

enum (TripType)

Bắt buộc. Đại diện cho loại chuyến đi đề xuất. Phải bao gồm đúng một loại. UNKNOWN_TRIP_TYPE là không được phép. Giới hạn tìm kiếm chỉ những xe có thể hỗ trợ loại chuyến đi đó.
maximumStaleness

string (Duration format)

Chỉ tìm kiếm những xe đã gửi thông tin cập nhật vị trí cho Fleet Engine trong khoảng thời gian nhất định. Các phương tiện tại chỗ vẫn truyền dữ liệu vị trí của chúng không bị coi là lỗi thời. Nếu bạn không đặt trường này, thì máy chủ sẽ sử dụng năm phút làm giá trị mặc định.

Thời lượng tính bằng giây với tối đa 9 chữ số phân số, kết thúc bằng "s". Ví dụ: "3.5s".
vehicleTypes[]

object (VehicleType)

Bắt buộc. Giới hạn tìm kiếm những xe thuộc một trong các loại đã chỉ định. Bạn phải chỉ định ít nhất một loại xe. Không được phép sử dụng các loại xe có danh mục UNKNOWN.
requiredAttributes[]

object (VehicleAttribute)

Phương thức gọi có thể tạo thành các phép toán logic phức tạp bằng cách sử dụng bất kỳ tổ hợp nào của các trường requiredAttributes, requiredOneOfAttributes và requiredOneOfAttributeSets.

requiredAttributes là một danh sách; requiredOneOfAttributes dùng một thông báo cho phép tạo một danh sách gồm các danh sách. Khi được kết hợp, 2 trường này cho phép thành phần của biểu thức này:

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

Giới hạn tìm kiếm chỉ cho những xe có các thuộc tính được chỉ định. Trường này là phép toán kết hợp/VÀ. Cho phép tối đa 50 requiredAttributes. Giá trị này khớp với số lượng thuộc tính tối đa được phép trên một chiếc xe.
requiredOneOfAttributes[]

object (VehicleAttributeList)

Giới hạn tìm kiếm chỉ cho những xe có ít nhất một trong các thuộc tính được chỉ định trong mỗi VehicleAttributeList. Trong mỗi danh sách, một chiếc xe phải khớp với ít nhất một trong các thuộc tính. Trường này là phép toán tách/HOẶC toàn diện trong mỗi VehicleAttributeList và phép kết hợp/VÀ trên tập hợp VehicleAttributeList.
requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets cung cấp chức năng bổ sung.

Tương tự như requiredOneOfAttributes, requiredOneOfAttributeSets sử dụng một thông báo cho phép tạo một danh sách gồm nhiều danh sách, cho phép các biểu thức như danh sách này:

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

Giới hạn tìm kiếm chỉ cho những xe có tất cả các thuộc tính trong VehicleAttributeList. Trong mỗi danh sách, một chiếc xe phải khớp với tất cả các thuộc tính. Trường này là phép toán kết hợp/VÀ trong mỗi VehicleAttributeList và phép tách/HOẶC bao gồm trên tập hợp VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

Bắt buộc. Chỉ định tiêu chí thứ tự mong muốn cho các kết quả.
includeBackToBack

boolean

Thuộc tính này cho biết liệu những phương tiện có một chuyến đi đang hoạt động có đủ điều kiện cho lượt tìm kiếm này hay không. Trường này chỉ được dùng khi bạn không chỉ định currentTripsPresent. Khi bạn chỉ định currentTripsPresent và trường này là false, những phương tiện được chỉ định chuyến đi sẽ bị loại trừ khỏi kết quả tìm kiếm. Khi bạn không chỉ định currentTripsPresent và trường này là true, kết quả tìm kiếm có thể bao gồm các xe có một chuyến đi đang hoạt động và có trạng thái là ENROUTE_TO_DROPOFF. Khi chỉ định currentTripsPresent, bạn không thể đặt trường này thành true.

Giá trị mặc định là false.
tripId

string

Cho biết chuyến đi được liên kết với SearchVehicleRequest này.
currentTripsPresent

enum (CurrentTripsPresent)

Thuộc tính này cho biết liệu phương tiện có chuyến đi đang hoạt động có đủ điều kiện cho nội dung tìm kiếm này hay không. Giá trị này phải được đặt thành giá trị khác với CURRENT_TRIPS_PRESENT_UNSPECIFIED nếu tripType bao gồm SHARED.
filter

string

Không bắt buộc. Một cụm từ tìm kiếm để áp dụng khi tìm kiếm xe. Hãy xem http://aip.dev/160 để biết ví dụ về cú pháp bộ lọc.

Trường này được thiết kế để thay thế các trường requiredAttributes, requiredOneOfAttributes và required_one_of_attributes_sets. Nếu bạn chỉ định giá trị không trống ở đây, thì các trường sau đây phải trống: requiredAttributes, requiredOneOfAttributes và required_one_of_attributes_sets.

Bộ lọc này hoạt động dưới dạng mệnh đề AND cùng với các điều kiện ràng buộc khác, chẳng hạn như minimumCapacity hoặc vehicleTypes.

Xin lưu ý rằng các truy vấn duy nhất được hỗ trợ là về các thuộc tính xe (ví dụ: attributes.<key> = <value> hoặc attributes.<key1> = <value1> AND attributes.<key2> = <value2>). Số lượng giới hạn tối đa được phép trong một truy vấn bộ lọc là 50.

Ngoài ra, mọi thuộc tính đều được lưu trữ dưới dạng chuỗi, do đó, phép so sánh duy nhất được hỗ trợ so với các thuộc tính là so sánh chuỗi. Để so sánh với giá trị số hoặc giá trị boolean, các giá trị phải được trích dẫn rõ ràng để được xử lý dưới dạng chuỗi (ví dụ: attributes.<key> = "10" hoặc attributes.<key> = "true").

Nội dung phản hồi

vehicles.search tin nhắn phản hồi.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
Trường
matches[]

object (VehicleMatch)

Danh sách xe đáp ứng tiêu chí SearchVehiclesRequest, được sắp xếp theo trường SearchVehiclesRequest.order_by.

VehicleAttributeList

Loại dữ liệu danh sách danh sách cho các thuộc tính xe.

Biểu diễn dưới dạng JSON 
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
Trường
attributes[]

object (VehicleAttribute)

Danh sách các thuộc tính trong tập hợp này.

VehicleMatchOrder

Chỉ định thứ tự của xe trùng khớp trong phản hồi.

Enum
UNKNOWN_VEHICLE_MATCH_ORDER Mặc định, dùng cho đơn đặt hàng trùng khớp xe không xác định hoặc không nhận dạng được.
PICKUP_POINT_ETA Thứ tự tăng dần theo thời gian lái xe đến điểm đón.
PICKUP_POINT_DISTANCE Thứ tự tăng dần theo quãng đường lái xe của xe đến điểm đón.
DROPOFF_POINT_ETA Thứ tự tăng dần theo thời gian lái xe đến điểm trả khách. Bạn chỉ có thể sử dụng đơn đặt hàng này nếu điểm trả khách được chỉ định trong yêu cầu.
PICKUP_POINT_STRAIGHT_DISTANCE Thứ tự tăng dần theo khoảng cách theo đường thẳng từ vị trí được báo cáo gần đây nhất của xe đến điểm đón.
COST Thứ tự tăng dần theo chi phí trùng khớp đã định cấu hình. Chi phí trùng khớp được định nghĩa là phép tính có trọng số giữa khoảng cách theo đường thẳng và giờ đến dự kiến. Trọng lượng được đặt theo giá trị mặc định và có thể sửa đổi theo từng khách hàng. Vui lòng liên hệ với nhóm hỗ trợ Google nếu cần sửa đổi các trọng số này cho dự án của bạn.

CurrentTripsPresent

Cho biết các loại quy định hạn chế đối với chuyến đi hiện tại của một xe.

Enum
CURRENT_TRIPS_PRESENT_UNSPECIFIED Tình trạng xe có cung cấp chuyến đi chịu sự điều chỉnh của trường includeBackToBack.
NONE Những chiếc xe không có chuyến đi có thể xuất hiện trong kết quả tìm kiếm. Khi dùng giá trị này, includeBackToBack không được là true.
ANY Những phương tiện có tối đa 5 chuyến đi hiện tại và 10 điểm tham chiếu sẽ được đưa vào kết quả tìm kiếm. Khi dùng giá trị này, includeBackToBack không được là true.

VehicleMatch

Chứa thông tin về xe và thông tin ước tính có liên quan cho một chiếc xe khớp với điểm của chuyến đi đang hoạt động của chiếc xe SearchVehiclesRequest.

Biểu diễn dưới dạng 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)
}
Trường
vehicle

object (Vehicle)

Bắt buộc. Một chiếc xe phù hợp với yêu cầu.
vehiclePickupEta

string (Timestamp format)

Thời gian đến dự kiến của xe đến điểm đón được chỉ định trong yêu cầu. Giá trị trống cho biết không tính toán thời gian đến dự kiến cho xe. Nếu SearchVehiclesRequest.include_back_to_back trước đây là true và xe này có một chuyến đi đang diễn ra, thì vehiclePickupEta sẽ bao gồm thời gian cần thiết để hoàn thành chuyến đi đang diễn ra hiện tại.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
vehiclePickupDistanceMeters

integer

Khoảng cách từ vị trí hiện tại của xe đến điểm đón khách được chỉ định trong yêu cầu, bao gồm cả mọi điểm đón hoặc trả xe trung gian cho những chuyến đi hiện có. Khoảng cách này bao gồm quãng đường lái xe (tuyến đường) được tính toán, cộng với khoảng cách đường thẳng giữa điểm cuối điều hướng và điểm đón khách được yêu cầu. (Khoảng cách giữa điểm cuối điều hướng và điểm đón nhận được yêu cầu thường nhỏ.) Giá trị trống cho biết có lỗi khi tính khoảng cách.
vehiclePickupStraightLineDistanceMeters

integer

Bắt buộc. Khoảng cách theo đường thẳng giữa xe và điểm đón khách được chỉ định trong yêu cầu.
vehicleDropoffEta

string (Timestamp format)

Giờ đến dự kiến của toàn bộ xe đến điểm trả khách được chỉ định trong yêu cầu. Giờ đến dự kiến bao gồm việc dừng tại bất kỳ điểm tham chiếu nào trước dropoffPoint được chỉ định trong yêu cầu. Giá trị sẽ chỉ được điền sẵn khi điểm trả khách được chỉ định trong yêu cầu. Giá trị trống cho biết có lỗi khi tính thời gian đến dự kiến.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
vehiclePickupToDropoffDistanceMeters

integer

Quãng đường lái xe của xe (tính bằng mét) từ điểm đón đến điểm trả khách được chỉ định trong yêu cầu. Khoảng cách này chỉ nằm giữa hai điểm và không bao gồm vị trí của xe hoặc bất kỳ điểm nào khác mà khách hàng phải ghé thăm trước khi xe ghé thăm điểm đón hoặc điểm trả xe. Giá trị sẽ chỉ được điền khi dropoffPoint được chỉ định trong yêu cầu. Giá trị trống cho biết không thể tính khoảng cách từ điểm đến lấy hàng đến điểm trả khách được chỉ định trong yêu cầu.
tripType

enum (TripType)

Bắt buộc. Loại chuyến đi trong yêu cầu được dùng để tính giờ đến dự kiến cho đến điểm đón.
vehicleTripsWaypoints[]

object (Waypoint)

Danh sách các điểm tham chiếu theo thứ tự dùng để tính toán thời gian đến dự kiến. Danh sách này bao gồm vị trí của xe, điểm đến lấy hàng của những chuyến đi đang hoạt động của xe và điểm đến lấy hàng được cung cấp trong yêu cầu. Danh sách trống cho biết không tính toán được thời gian đến dự kiến cho xe.
vehicleMatchType

enum (VehicleMatchType)

Loại xe trùng khớp.
requestedOrderedBy

enum (VehicleMatchOrder)

Thứ tự yêu cầu sắp xếp xe trùng khớp.
orderedBy

enum (VehicleMatchOrder)

Đơn đặt hàng thực tế được sử dụng cho xe này. Thông thường, giá trị này sẽ khớp với giá trị "orderBy" khỏi yêu cầu; tuy nhiên, trong một số trường hợp nhất định (chẳng hạn như lỗi máy chủ nội bộ), bạn có thể sử dụng một phương thức khác (chẳng hạn như PICKUP_POINT_STRAIGHT_DISTANCE).

Waypoint

Mô tả các điểm trung gian dọc theo một tuyến đường của VehicleMatch trong SearchVehiclesResponse. Khái niệm này được biểu thị dưới dạng TripWaypoint trong tất cả các điểm cuối khác.

Biểu diễn dưới dạng JSON 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
Trường
latLng

object (LatLng)

Vị trí của điểm tham chiếu này.
eta

string (Timestamp format)

Thời gian ước tính mà xe sẽ đến điểm tham chiếu này.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".

VehicleMatchType

Loại xe trùng khớp.

Enum
UNKNOWN Kiểu xe không xác định
EXCLUSIVE Chiếc xe này hiện chưa được chỉ định chuyến đi nào và có thể đi đến điểm đón.
BACK_TO_BACK Xe hiện được chỉ định cho một chuyến đi nhưng có thể đi đến điểm đón sau khi bạn hoàn tất chuyến đi đang diễn ra. Giờ đến dự kiến và các phép tính khoảng cách có tính đến chuyến đi hiện tại.
CARPOOL Xe có đủ sức chứa cho một chuyến đi chung.
CARPOOL_BACK_TO_BACK Xe sẽ kết thúc chuyến đi hiện tại đang diễn ra trước khi đến điểm đón. Giờ đến dự kiến và các phép tính khoảng cách có tính đến chuyến đi hiện tại.