Method: providers.vehicles.search

تعرض قائمة بالمركبات التي تتطابق مع خيارات الطلب.

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
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.
pickupPoint

object (TerminalLocation)

مطلوبة. نقطة الاستلام للبحث بالقرب منها.
dropoffPoint

object (TerminalLocation)

موقع التسليم المقصود للعميل. يجب ملء هذا الحقل إذا كان tripTypes يحتوي على TripType.SHARED.
pickupRadiusMeters

integer

مطلوبة. لتحديد نصف قطر البحث عن المركبة حول نقطة الاستلام. وسيتمّ عرض المركبات ضمن نطاق البحث فقط. ويجب أن تتراوح القيمة بين 400 و10,000 متر (شاملةً).
count

integer

مطلوبة. تحدّد هذه السمة الحد الأقصى لعدد المركبات المطلوب إرجاعها. يجب أن تتراوح القيمة بين 1 و50 (شاملةً).
minimumCapacity

integer

مطلوبة. لتحديد عدد الركاب الذين سيتم أخذهم في الاعتبار لإجراء رحلة. يجب أن تكون القيمة أكبر من واحد أو مساوية له. لم يتم تضمين السائق في قيمة السعة.
tripTypes[]

enum (TripType)

مطلوبة. يمثّل هذا المقياس نوع الرحلة المقترَحة. يجب أن تتضمن نوعًا واحدًا بالضبط. لا يُسمح باستخدام UNKNOWN_TRIP_TYPE. حصر عملية البحث على المركبات التي تتيح استخدام نوع الرحلة هذا فقط.
maximumStaleness

string (Duration format)

يقصر البحث على المركبات التي أرسلت تحديثات الموقع الجغرافي إلى Fleet Engine خلال المدة المحددة. ولا تعتبر المركبات الثابتة التي لا تزال تنقل مواقعها قديمة. وفي حال عدم ضبط هذا الحقل، سيستخدم الخادم خمس دقائق كقيمة تلقائية.

مدة بالثواني مؤلفة من تسعة أرقام كسور وتنتهي بـ "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
...)

تقتصر عملية البحث على المركبات ذات السمات المحدّدة فقط. هذا الحقل هو عملية ربط/و. الحد الأقصى المسموح به لعدد السمات هو 50 سمة. تتطابق هذه السمة مع الحد الأقصى لعدد السمات المسموح بها في المركبة.
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 وعملية فاصلة/أو شاملة في مجموعة VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

مطلوبة. تحدد معيار الترتيب المطلوب للنتائج.
includeBackToBack

boolean

يشير هذا إلى ما إذا كانت المركبات التي تشمل رحلة نشطة واحدة مؤهّلة لإجراء عملية البحث هذه. ولا يتم استخدام هذا الحقل إلا في حال عدم تحديد currentTripsPresent. في حال عدم تحديد قيمة السمة currentTripsPresent وكان هذا الحقل هو false، يتم استبعاد المركبات ذات رحلاتها المخصّصة من نتائج البحث. في حال عدم تحديد currentTripsPresent وكان هذا الحقل هو true، يمكن أن تتضمّن نتائج البحث مركبات لها رحلة نشطة واحدة بالحالة ENROUTE_TO_DROPOFF. عند تحديد currentTripsPresent، لا يمكن ضبط هذا الحقل على "صحيح".

ستكون القيمة التلقائية false.
tripId

string

تشير هذه السمة إلى الرحلة المرتبطة بجهاز SearchVehicleRequest هذا.
currentTripsPresent

enum (CurrentTripsPresent)

يشير ذلك إلى ما إذا كانت المركبات ذات الرحلات النشطة مؤهَّلة لإجراء عملية البحث هذه. ويجب ضبط هذه السمة على قيمة أخرى غير CURRENT_TRIPS_PRESENT_UNSPECIFIED إذا كانت السمة tripType تتضمّن SHARED.
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").

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال SearchVehiclesResponse.