Method: providers.vehicles.search

Trả về danh sách các xe phù hợp với các tuỳ chọn 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

Tham 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 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 đề yêu cầu thông thường của Công cụ của đội xe.
pickupPoint

object (TerminalLocation)

Bắt buộc. Điểm đến lấy hàng để tìm kiếm ở gần.
dropoffPoint

object (TerminalLocation)

Địa điểm giao hàng mà khách hàng dự định. Trường này là 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 đón. Hệ thống sẽ chỉ trả về những chiếc xe nằm trong 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. Chỉ định 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. Chỉ định số lượng hành khách đang được xem xét cho một chuyến đi. Giá trị phải lớn hơn hoặc bằng 1. Người lái xe không được tính trong giá trị sức chứa.
tripTypes[]

enum (TripType)

Bắt buộc. Biểu thị loại chuyến đi được đề xuất. Phải có đúng một loại. UNKNOWN_TRIP_TYPE là không được phép. Chỉ cho phép tìm kiếm những loại xe có thể hỗ trợ loại chuyến đi đó.
maximumStaleness

string (Duration format)

Chỉ cho phép tìm kiếm những xe đã gửi thông tin cập nhật vị trí đến Công cụ quản lý đội xe trong khoảng thời gian đã chỉ định. Xe đang đỗ vẫn truyền vị trí của chúng không được coi là cũ. Nếu bạn không đặt trường này, máy chủ sẽ sử dụng 5 phút làm giá trị mặc định.

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

object (VehicleType)

Bắt buộc. Hạn chế kết quả tìm kiếm ở những loại 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 VehicleTypes có danh mục là UNKNOWN.
requiredAttributes[]

object (VehicleAttribute)

Phương thức gọi có thể tạo 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 sử dụng một thông báo cho phép danh sách danh sách. Khi kết hợp, hai 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
...)

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

object (VehicleAttributeList)

Chỉ cho phép tìm kiếm những chiếc 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 xe phải khớp với ít nhất một thuộc tính. Trường này là một toán tử loại trừ/OR bao gồm trong mỗi VehicleAttributeList và một toán tử kết hợp/AND 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 danh sách danh sách, cho phép các biểu thức như sau:

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

Chỉ cho phép tìm kiếm những chiếc xe có tất cả các thuộc tính trong VehicleAttributeList. Trong mỗi danh sách, một xe phải khớp với tất cả các thuộc tính. Trường này là một toán tử kết hợp/AND trong mỗi VehicleAttributeList và toán tử loại trừ bao hàm/OR trên tập hợp VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

Bắt buộc. Chỉ định tiêu chí sắp xếp mong muốn cho kết quả.
includeBackToBack

boolean

Giá trị này cho biết liệu những chiếc xe 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 currentTripsPresent không được chỉ định. Khi currentTripsPresent không được chỉ định và trường này là false, các phương tiện có chuyến đi được chỉ định sẽ bị loại trừ khỏi kết quả tìm kiếm. Khi currentTripsPresent không được chỉ định 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 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)

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

string

Không bắt buộc. Truy vấn bộ lọc để á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 một giá trị không trống tại đây, thì các trường sau phải để trống: requiredAttributes, requiredOneOfAttributes và required_one_of_attributes_sets.

Bộ lọc này hoạt động như một mệnh đề AND với các quy tắc 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 của xe (ví dụ: attributes.<key> = <value> hoặc attributes.<key1> = <value1> AND attributes.<key2> = <value2>). Số lượng hạn chế tối đa được phép trong một truy vấn bộ lọc là 50.

Ngoài ra, tất cả các thuộc tính đều được lưu trữ dưới dạng chuỗi, vì vậy, việc so sánh duy nhất được hỗ trợ đối với các thuộc tính là so sánh chuỗi. Để so sánh với giá trị số hoặc boolean, các giá trị đó phải được đặt trong dấu ngoặc kép rõ ràng để được coi là chuỗi (ví dụ: attributes.<key> = "10" hoặc attributes.<key> = "true").

Nội dung phản hồi

Thông báo phản hồi vehicles.search.

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 phù hợp với 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 của 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 bộ sưu tập này.

VehicleMatchOrder

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

Enum
UNKNOWN_VEHICLE_MATCH_ORDER Mặc định, dùng cho đơn đặt hàng khớp với xe không được chỉ định hoặc không được nhận dạng.
PICKUP_POINT_ETA Sắp xếp theo thứ tự tăng dần theo thời gian lái xe đến điểm đến lấy hàng.
PICKUP_POINT_DISTANCE Sắp xếp theo thứ tự tăng dần theo quãng đường lái xe đến điểm đến lấy hàng.
DROPOFF_POINT_ETA Sắp xếp theo 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ả hàng được chỉ định trong yêu cầu.
PICKUP_POINT_STRAIGHT_DISTANCE Sắp xếp 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í khớp đã định cấu hình. Chi phí khớp được xác định là kết quả tính toán theo trọng số giữa khoảng cách theo đường thẳng và ETA. Hệ số được đặt bằng các giá trị mặc định và có thể được 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 bạn cần sửa đổi các trọng số này cho dự án của mình.

CurrentTripsPresent

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

Enum
CURRENT_TRIPS_PRESENT_UNSPECIFIED Tình trạng còn xe của những xe có chuyến đi được điều chỉnh theo trường includeBackToBack.
NONE Xe không có chuyến đi có thể xuất hiện trong kết quả tìm kiếm. Khi sử dụng giá trị này, includeBackToBack không được là true.
ANY Những xe có tối đa 5 chuyến đi hiện tại và 10 điểm trung gian sẽ xuất hiện trong kết quả tìm kiếm. Khi sử dụng giá trị này, includeBackToBack không được là true.

VehicleMatch

Chứa xe và số liệu ước tính liên quan cho một xe khớp với các điểm của chuyến đi đang hoạt động cho 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 dự kiến đến điểm đón của xe theo đường bộ được chỉ định trong yêu cầu. Giá trị trống cho biết không tính toán được ETA cho xe. Nếu SearchVehiclesRequest.include_back_to_back là true và xe này có một chuyến đi đang hoạt động, thì vehiclePickupEta sẽ bao gồm thời gian cần thiết để hoàn tất chuyến đi đang hoạt động hiện tại.

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. 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 được chỉ định trong yêu cầu, bao gồm mọi điểm đón hoặc trả khách trung gian cho các chuyến đi hiện tại. Khoảng cách này bao gồm khoảng cách lái xe (tuyến đường) được tính toán, cộng với khoảng cách theo đường thẳng giữa điểm cuối của hành trình và điểm đón được yêu cầu. (Khoảng cách giữa điểm kết thúc chỉ đường và điểm đến lấy hàng thường nhỏ.) Giá trị trống cho biết có lỗi trong quá trình tính toán 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 được chỉ định trong yêu cầu.
vehicleDropoffEta

string (Timestamp format)

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

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. 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 chỉ tính 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à xe phải ghé thăm trước khi đến điểm đón hoặc điểm trả khách. Giá trị này sẽ chỉ được điền khi bạn chỉ định dropoffPoint trong yêu cầu. Giá trị trống cho biết không tính được khoảng cách từ điểm đón đế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 của yêu cầu được dùng để tính thời gian đến điểm đón.
vehicleTripsWaypoints[]

object (Waypoint)

Danh sách điểm trung gian được sắp xếp dùng để tính toán ETA. Danh sách này bao gồm vị trí của xe, điểm đến lấy hàng của các chuyến đi đang hoạt động cho 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 được ETA cho xe.
vehicleMatchType

enum (VehicleMatchType)

Loại kiểu khớp xe.
requestedOrderedBy

enum (VehicleMatchOrder)

Thứ tự được yêu cầu để sắp xếp các kết quả trùng khớp về xe. Tương đương với orderedBy.
orderedBy

enum (VehicleMatchOrder)

Thứ tự yêu cầu để sắp xếp các kết quả trùng khớp về xe. Tương đương với requestedOrderedBy.

Waypoint

Mô tả các điểm trung gian dọc theo tuyến đường cho 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 trung gian này.
eta

string (Timestamp format)

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

Dấu thời gian ở định dạng "Zulu" RFC3339 UTC, có độ phân giải nano giây và tối đa 9 chữ số thập phân. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".

VehicleMatchType

Loại thông tin khớp về xe.

Enum
UNKNOWN Loại kết quả so khớp xe không xác định
EXCLUSIVE Xe hiện không có chuyến đi nào được chỉ định và có thể tiếp tục đến điểm đón.
BACK_TO_BACK Xe hiện được chỉ định cho một chuyến đi, nhưng có thể tiếp tục đến điểm đón sau khi hoàn tất chuyến đi đang diễn ra. Tính toán khoảng cách và thời gian đến dự kiến sẽ tính đến chuyến đi hiện tại.
CARPOOL Xe có đủ chỗ cho một chuyến đi chung.
CARPOOL_BACK_TO_BACK Xe sẽ hoàn tất chuyến đi đang hoạt động trước khi đến điểm đón. Tính toán khoảng cách và thời gian đến dự kiến sẽ tính đến chuyến đi hiện tại.