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

يحصر البحث بالمركبات التي تتضمّن السمات المحدّدة فقط. هذا الحقل هو عملية ربط/AND. يُسمح بحد أقصى 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 فقط. ويجب أن تتطابق المركبة مع جميع السمات ضمن كل قائمة. هذا الحقل هو عملية ربط/AND في كل VehicleAttributeList وعملية نفي شامل/OR في مجموعة 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 "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
vehiclePickupDistanceMeters

integer

المسافة من الموقع الجغرافي الحالي للمركبة إلى نقطة الاستلام المحدّدة في الطلب، بما في ذلك أي نقاط استلام أو نقاط تسليم وسيطة للرحلات الحالية تتألف هذه المسافة من المسافة المحسوبة للقيادة (المسار) بالإضافة إلى المسافة المستقيمة بين نقطة نهاية التنقّل ونقطة الاستلام المطلوبة. (تكون المسافة بين نقطة نهاية التنقّل ونقطة الاستلام المطلوبة عادةً صغيرة.) تشير القيمة الفارغة إلى خطأ في احتساب المسافة.
vehiclePickupStraightLineDistanceMeters

integer

مطلوب. المسافة المستقيمة بين المركبة ونقطة الاستلام المحدّدة في الطلب
vehicleDropoffEta

string (Timestamp format)

وقت الوصول المقدَّر الكامل للمركبة بالقيادة إلى نقطة الاستلام المحدّدة في الطلب يتضمّن وقت الوصول المقدَّر التوقف في أي نقاط طريق قبل dropoffPoint المحدَّدة في الطلب. لن تتم تعبئة القيمة إلا عند تحديد نقطة تسليم في الطلب. تشير القيمة الفارغة إلى خطأ في احتساب وقت الوصول المقدَّر.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "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.
orderedBy

enum (VehicleMatchOrder)

الطلب المطلوب لترتيب مطابقات المركبات. هذا الرمز مكافئ للرمز requestedOrderedBy.

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

يصف النقاط الوسيطة على طول مسار VehicleMatch في SearchVehiclesResponse. يتم تمثيل هذا المفهوم على أنّه TripWaypoint في جميع نقاط النهاية الأخرى.

تمثيل JSON 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
الحقول
latLng

object (LatLng)

الموقع الجغرافي لنقطة الطريق هذه.
eta

string (Timestamp format)

الوقت المقدَّر الذي ستصل فيه المركبة إلى نقطة المرور هذه.

يجب أن يكون طابعًا زمنيًا بالتنسيق RFC3339 UTC "Zulu"‎ وبدقة تصل إلى نانوثانية وما يصل إلى تسعة أرقام كسور. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"

VehicleMatchType

نوع مطابقة المركبة

عمليات التعداد
UNKNOWN نوع مطابقة المركبة غير معروف
EXCLUSIVE لم يتم إسناد رحلة إلى المركبة حاليًا ويمكنها المتابعة إلى نقطة الاستلام.
BACK_TO_BACK تمّ إسناد المركبة حاليًا إلى رحلة، ولكن يمكنها المتابعة إلى نقطة الاستلام بعد إكمال الرحلة قيد التقدّم. تأخذ عمليات احتساب الوقت المقدَّر للوصول والمسافة الرحلة الحالية في الاعتبار.
CARPOOL أن تكون المركبة ذات سعة كافية لنقل ركاب إضافيين
CARPOOL_BACK_TO_BACK ستنتهي المركبة من رحلتها النشطة الحالية قبل المتابعة إلى نقطة الاستلام. تأخذ عمليات احتساب الوقت المقدَّر للوصول والمسافة الرحلة الحالية في الاعتبار.