Method: providers.vehicles.search

فهرستی از وسایل نقلیه را برمی‌گرداند که با گزینه‌های درخواست مطابقت دارند.

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

پارامترهای مسیر

پارامترها
parent

string

مورد نیاز. باید در قالب providers/{provider} باشد. ارائه‌دهنده باید شناسه پروژه (به عنوان مثال، sample-cloud-project ) پروژه Google Cloud باشد که حساب سرویسی که این تماس را برقرار می‌کند عضوی از آن است.

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی 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.

pickup Point

object ( TerminalLocation )

مورد نیاز. نقطه تحویل برای جستجو در نزدیکی.

dropoff Point

object ( TerminalLocation )

محل خروج مورد نظر مشتری اگر tripTypes حاوی TripType.SHARED باشد، فیلد مورد نیاز است.

pickup Radius Meters

integer

مورد نیاز. شعاع جستجوی وسیله نقلیه را در اطراف نقطه وانت تعریف می کند. فقط وسایل نقلیه در شعاع جستجو بازگردانده خواهند شد. مقدار باید بین 400 تا 10000 متر (شامل) باشد.

count

integer

مورد نیاز. حداکثر تعداد وسایل نقلیه برای بازگشت را مشخص می کند. مقدار باید بین 1 تا 50 باشد (شامل).

minimum Capacity

integer

مورد نیاز. تعداد مسافرانی که برای یک سفر در نظر گرفته شده اند را مشخص می کند. مقدار باید بزرگتر یا مساوی یک باشد. راننده در مقدار ظرفیت در نظر گرفته نمی شود.

trip Types[]

enum ( TripType )

مورد نیاز. نشان دهنده نوع سفر پیشنهادی است. باید دقیقاً یک نوع را شامل شود. UNKNOWN_TRIP_TYPE مجاز نیست. جستجو را فقط به وسایل نقلیه‌ای محدود می‌کند که می‌توانند آن نوع سفر را پشتیبانی کنند.

maximum Staleness

string ( Duration format)

جستجو را فقط به وسایل نقلیه‌ای محدود می‌کند که در مدت زمان مشخص شده به‌روزرسانی‌های مکان را به Fleet Engine ارسال کرده‌اند. وسایل نقلیه ثابتی که هنوز مکان خود را مخابره می کنند کهنه در نظر گرفته نمی شوند. اگر این فیلد تنظیم نشده باشد، سرور از پنج دقیقه به عنوان مقدار پیش فرض استفاده می کند.

مدت زمان در ثانیه با حداکثر نه رقم کسری که با ' s ' ختم می شود. مثال: "3.5s" .

vehicle Types[]

object ( VehicleType )

مورد نیاز. جستجو را به خودروهایی با یکی از انواع مشخص شده محدود می کند. حداقل یک نوع وسیله نقلیه باید مشخص شود. انواع خودرو با دسته UNKNOWN مجاز نیستند.

required Attributes[]

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 ویژگی مورد نیاز مجاز است. این با حداکثر تعداد مشخصه های مجاز در یک وسیله نقلیه مطابقت دارد.

required One Of Attributes[]

object ( VehicleAttributeList )

جستجو را فقط به آن دسته از وسایل نقلیه با حداقل یکی از ویژگی های مشخص شده در هر VehicleAttributeList محدود می کند. در هر فهرست، یک وسیله نقلیه باید حداقل با یکی از ویژگی ها مطابقت داشته باشد. این فیلد یک عملیات تفکیک/OR فراگیر در هر VehicleAttributeList و یک عملیات ربط/AND در مجموعه VehicleAttributeList است.

required One Of Attribute Sets[]

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 و عملیات تفکیک/OR فراگیر در مجموعه VehicleAttributeList است.

order By

enum ( VehicleMatchOrder )

مورد نیاز. معیار سفارش مورد نظر را برای نتایج مشخص می کند.

include Back To Back

boolean

این نشان می دهد که آیا وسایل نقلیه با یک سفر فعال واجد شرایط این جستجو هستند یا خیر. این فیلد فقط زمانی استفاده می شود که currentTripsPresent مشخص نشده باشد. هنگامی که currentTripsPresent مشخص نشده باشد و این فیلد false باشد، وسایل نقلیه با سفرهای اختصاص داده شده از نتایج جستجو حذف می شوند. هنگامی که currentTripsPresent مشخص نشده باشد و این قسمت true باشد، نتایج جستجو می تواند شامل وسایل نقلیه با یک سفر فعال باشد که وضعیت آن ENROUTE_TO_DROPOFF است. هنگامی که currentTripsPresent مشخص شده است، این فیلد را نمی توان روی true تنظیم کرد.

مقدار پیش فرض false است.

trip Id

string

نشان دهنده سفر مرتبط با این SearchVehicleRequest است.

current Trips Present

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

ترتیب مطابقت های وسیله نقلیه را در پاسخ مشخص می کند.

Enums
UNKNOWN_VEHICLE_MATCH_ORDER پیش‌فرض، برای ترتیب تطبیق خودروهای نامشخص یا ناشناخته استفاده می‌شود.
PICKUP_POINT_ETA ترتیب صعودی بر اساس زمان رانندگی وسیله نقلیه تا نقطه وانت.
PICKUP_POINT_DISTANCE ترتیب صعودی بر اساس فاصله رانندگی وسیله نقلیه تا نقطه وانت.
DROPOFF_POINT_ETA ترتیب صعودی بر اساس زمان رانندگی وسیله نقلیه تا نقطه سقوط. این سفارش تنها در صورتی قابل استفاده است که نقطه خروج در درخواست مشخص شده باشد.
PICKUP_POINT_STRAIGHT_DISTANCE ترتیب صعودی بر اساس فاصله خط مستقیم از آخرین مکان گزارش شده خودرو تا نقطه تحویل.
COST ترتیب صعودی بر اساس هزینه بازی پیکربندی شده. هزینه مسابقه به عنوان یک محاسبه وزنی بین فاصله خط مستقیم و ETA تعریف می شود. وزن‌ها با مقادیر پیش‌فرض تنظیم می‌شوند و به ازای هر مشتری قابل تغییر هستند. اگر این وزن ها برای پروژه شما نیاز به تغییر دارند، لطفاً با پشتیبانی Google تماس بگیرید.

CurrentTripsPresent

انواع محدودیت ها را در سفرهای فعلی یک وسیله نقلیه مشخص می کند.

Enums
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 )

مورد نیاز. وسیله نقلیه ای که با درخواست مطابقت دارد.

vehicle Pickup Eta

string ( Timestamp format)

رانندگی ETA خودرو به نقطه تحویل مشخص شده در درخواست. مقدار خالی نشان دهنده نقص در محاسبه ETA برای خودرو است. اگر SearchVehiclesRequest.include_back_to_back true بود و این وسیله نقلیه یک سفر فعال دارد، vehiclePickupEta شامل زمان مورد نیاز برای تکمیل سفر فعال فعلی است.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

vehicle Pickup Distance Meters

integer

فاصله از مکان فعلی وسیله نقلیه تا نقطه تحویل مشخص شده در درخواست، از جمله هر نقطه میانی تحویل یا خروج برای سفرهای موجود. این فاصله شامل فاصله رانندگی (مسیر) محاسبه شده، به اضافه فاصله خط مستقیم بین نقطه پایان ناوبری و نقطه تحویل درخواستی است. (فاصله بین نقطه پایان ناوبری و نقطه دریافت درخواستی معمولاً کوچک است.) مقدار خالی نشان دهنده خطا در محاسبه فاصله است.

vehicle Pickup Straight Line Distance Meters

integer

مورد نیاز. فاصله خط مستقیم بین وسیله نقلیه و نقطه وانت مشخص شده در درخواست.

vehicle Dropoff Eta

string ( Timestamp format)

رانندگی کامل وسیله نقلیه تا نقطه سقوط مشخص شده در درخواست. ETA شامل توقف در هر نقطه بین راهی قبل از dropoffPoint مشخص شده در درخواست است. مقدار فقط زمانی پر می شود که یک نقطه رها کردن در درخواست مشخص شده باشد. مقدار خالی نشان دهنده خطا در محاسبه ETA است.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

vehicle Pickup To Dropoff Distance Meters

integer

فاصله رانندگی وسیله نقلیه (بر حسب متر) از نقطه تحویل تا نقطه سقوط مشخص شده در درخواست. فاصله فقط بین دو نقطه است و شامل مکان وسیله نقلیه یا هر نقطه دیگری که باید قبل از بازدید وسیله نقلیه از نقطه تحویل و یا نقطه سقوط از آن بازدید شود، نمی شود. مقدار فقط زمانی پر می شود که یک dropoffPoint در درخواست مشخص شده باشد. یک مقدار خالی نشان دهنده خطا در محاسبه فاصله از پیکاپ تا نقطه خروج مشخص شده در درخواست است.

trip Type

enum ( TripType )

مورد نیاز. نوع سفر درخواستی که برای محاسبه ETA به نقطه تحویل استفاده شد.

vehicle Trips Waypoints[]

object ( Waypoint )

فهرست مرتب شده ای از نقاط مورد استفاده برای محاسبه ETA. این لیست شامل مکان وسیله نقلیه، نقاط وانت سفرهای فعال برای وسیله نقلیه و نقاط وانت ارائه شده در درخواست است. لیست خالی نشان دهنده نقص در محاسبه ETA برای خودرو است.

vehicle Match Type

enum ( VehicleMatchType )

نوع مطابقت وسیله نقلیه

requested Ordered By

enum ( VehicleMatchOrder )

سفارش درخواست شده برای مرتب سازی مسابقات خودرو.

ordered By

enum ( VehicleMatchOrder )

سفارش واقعی که برای این وسیله نقلیه استفاده شده است. معمولاً این با فیلد «orderBy» از درخواست مطابقت دارد. با این حال، در شرایط خاصی مانند خطای سرور داخلی، ممکن است از روش دیگری استفاده شود (مانند PICKUP_POINT_STRAIGHT_DISTANCE ).

نقطه راه

نقاط میانی را در طول یک مسیر برای VehicleMatch در SearchVehiclesResponse توصیف می کند. این مفهوم به عنوان یک TripWaypoint در تمام نقاط پایانی دیگر نشان داده می شود.

نمایندگی JSON 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
فیلدها
lat Lng

object ( LatLng )

محل این ایستگاه بین راهی.

eta

string ( Timestamp format)

زمان تخمینی که وسیله نقلیه به این نقطه می رسد.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

VehicleMatchType

نوع مسابقه وسیله نقلیه

Enums
UNKNOWN نوع تطبیق وسیله نقلیه ناشناخته
EXCLUSIVE این وسیله نقلیه در حال حاضر هیچ سفری برای آن تعیین نشده است و می تواند به نقطه وانت ادامه دهد.
BACK_TO_BACK وسیله نقلیه در حال حاضر به یک سفر اختصاص داده شده است، اما می تواند پس از تکمیل سفر در حال انجام، به نقطه وانت ادامه دهد. ETA و محاسبات مسافت، سفر موجود را در نظر می گیرند.
CARPOOL این وسیله نقلیه دارای ظرفیت کافی برای یک سواری مشترک است.
CARPOOL_BACK_TO_BACK خودرو قبل از رفتن به نقطه وانت، سفر فعلی و فعال خود را به پایان خواهد رساند. ETA و محاسبات مسافت، سفر موجود را در نظر می گیرند.