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").

نص الاستجابة

رسالة رد واحدة (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)

الوقت المقدَّر لقيادة المركبة بالكامل عند الوصول إلى نقطة التسليم المحدّدة في الطلب ويشمل الوقت المقدر للوصول التوقف عند أي نقاط طريق قبل 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

enum (VehicleMatchOrder)

الطلب الفعلي الذي تم استخدامه لهذه المركبة. عادةً ما يتطابق هذا مع ترتيب "orderBy" من الطلب؛ ولكن في بعض الحالات مثل الخطأ الداخلي في الخادم، قد يتم استخدام طريقة مختلفة (مثل PICKUP_POINT_STRAIGHT_DISTANCE).

النقطة الوسيطة

يصف هذا المقياس النقاط المتوسطة على طول مسار VehicleMatch في SearchVehiclesResponse. ويُشار إلى هذا المفهوم على أنّه 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 ستُنهي المركبة رحلتها الحالية النشطة قبل المتابعة إلى نقطة الاستلام. وتراعي حسابات الوقت المقدّر للوصول والمسافة الرحلة الحالية.