- طلب HTTP
- مَعلمات المسار
- نص الطلب
- نص الاستجابة
- VehicleAttributeList
- VehicleMatchOrder
- CurrentTripsPresent
- VehicleMatch
- نقطة المسار
- VehicleMatchType
تعرض قائمة بالمركبات التي تتطابق مع خيارات الطلب.
طلب HTTP
POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات المسار
المَعلمات | |
---|---|
parent |
مطلوبة. يجب استخدام التنسيق |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "header": { object ( |
الحقول | |
---|---|
header |
عنوان طلب Fleet Engine العادي |
pickupPoint |
مطلوبة. نقطة الاستلام للبحث بالقرب منها. |
dropoffPoint |
موقع التسليم المقصود للعميل. يجب ملء هذا الحقل إذا كان |
pickupRadiusMeters |
مطلوبة. لتحديد نصف قطر البحث عن مركبة حول نقطة الاستلام. ولن يتمّ عرض سوى المركبات ضمن نصف قطر البحث. ويجب أن تتراوح القيمة بين 400 و10,000 متر (شاملةً). |
count |
مطلوبة. تحدّد هذه السمة الحدّ الأقصى لعدد المركبات التي يمكن إرجاعها. يجب أن تتراوح القيمة بين 1 و50 (شاملةً). |
minimumCapacity |
مطلوبة. لتحديد عدد الركاب الذين يتم أخذهم في الاعتبار للرحلة. يجب أن تكون القيمة أكبر من واحد أو مساوية له. لم يتم أخذ السائق في الاعتبار ضمن قيمة السعة. |
tripTypes[] |
مطلوبة. تمثّل هذه السمة نوع الرحلة المقترَحة. يجب أن تتضمن نوعًا واحدًا فقط. لا يُسمح باستخدام |
maximumStaleness |
يقصر البحث على المركبات التي أرسلت تحديثات الموقع إلى Fleet Engine خلال المدة المحددة. ولا تعتبر المركبات الثابتة التي لا تزال تنقل مواقعها قديمة. وفي حال عدم ضبط هذا الحقل، سيستخدم الخادم خمس دقائق فقط كقيمة تلقائية. مدة بالثواني يصل عددها إلى تسعة أرقام كسرية وتنتهي بـ " |
vehicleTypes[] |
مطلوبة. يحصر البحث بالمركبات ذات أحد الأنواع المحددة. يجب تحديد نوع مركبة واحد على الأقل. لا يُسمح بأنواع المركبات من الفئة |
requiredAttributes[] |
يمكن للمتصلين إنشاء عمليات منطقية معقدة باستخدام أي مجموعة من الحقول
يقصر البحث على المركبات ذات السمات المحددة فقط. هذا الحقل هو عملية اقتران/و. يُسمح بـ 50 requiredAttributes كحد أقصى. تتطابق هذه السمة مع الحد الأقصى لعدد السمات المسموح بها في المركبة. |
requiredOneOfAttributes[] |
يقتصر البحث على المركبات التي تتضمّن سمة واحدة على الأقل من السمات المحدَّدة في كل |
requiredOneOfAttributeSets[] |
يوفّر على غرار
تقتصر عملية البحث على المركبات التي تتضمّن جميع السمات في |
orderBy |
مطلوبة. تحدّد هذه السمة معيار الترتيب المطلوب للنتائج. |
includeBackToBack |
يشير ذلك إلى ما إذا كانت المركبات التي لها رحلة نشطة واحدة مؤهّلة لعملية البحث هذه. لا يتم استخدام هذا الحقل إلا في حال عدم تحديد تكون القيمة التلقائية |
tripId |
يشير هذا العمود إلى الرحلة المرتبطة بجهاز " |
currentTripsPresent |
ويشير هذا إلى ما إذا كانت المركبات التي لها رحلات نشطة مؤهّلة لهذا البحث. ويجب ضبطها على قيمة أخرى غير |
filter |
اختياريّ. استعلام فلتر ليتم تطبيقه عند البحث عن المركبات. راجِع http://aip.dev/160 للحصول على أمثلة على بنية الفلتر. تم تصميم هذا الحقل ليحل محل الحقول ويعمل هذا الفلتر كعبارة AND مع قيود أخرى، مثل يُرجى العِلم أنّ طلبات البحث الوحيدة المتاحة هي في سمات المركبات (مثل يتم أيضًا تخزين جميع السمات كسلاسل، وبالتالي فإنّ المقارنات الوحيدة المتوافقة مع السمات هي مقارنات السلاسل. للمقارنة مع القيم الرقمية أو المنطقية، يجب اقتباس القيم صراحةً ليتم التعامل معها كسلاسل (على سبيل المثال، |
نص الاستجابة
رسالة رد واحدة (vehicles.search
)
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"matches": [
{
object ( |
الحقول | |
---|---|
matches[] |
قائمة بالمركبات التي تستوفي معايير |
VehicleAttributeList
تمثّل هذه السمة نوع بيانات قائمة من القوائم لسمات المركبات.
تمثيل JSON |
---|
{
"attributes": [
{
object ( |
الحقول | |
---|---|
attributes[] |
تمثّل هذه السمة قائمة بالسمات في هذه المجموعة. |
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 |
تشير هذه السمة إلى الوقت المقدَّر للوصول للقيادة في المركبة إلى نقطة الاستلام المحدّدة في الطلب. تشير القيمة الفارغة إلى تعذّر احتساب الوقت المقدّر للوصول للمركبة. إذا كانت قيمة الحقل " طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
vehiclePickupDistanceMeters |
المسافة من الموقع الجغرافي الحالي للمركبة إلى نقطة الاستلام المحدّدة في الطلب، بما في ذلك أي نقاط استلام أو هبوط متوسطة للرحلات الحالية وتضم هذه المسافة مسافة القيادة (الطريق) المحسوبة، بالإضافة إلى مسافة الخط المستقيم بين نقطة نهاية التنقل ونقطة الاستلام المطلوبة. (تكون المسافة بين نقطة نهاية التنقّل ونقطة الاستلام المطلوبة عادةً صغيرة). أما القيمة الفارغة، فتشير إلى حدوث خطأ في حساب المسافة. |
vehiclePickupStraightLineDistanceMeters |
مطلوبة. هذه السمة تعرض المسافة المستقيمة بين المركبة ونقطة الاستلام المحدّدة في الطلب. |
vehicleDropoffEta |
الوقت المقدّر للوصول للمركبة بالكامل إلى نقطة التسليم المحدَّدة في الطلب. ويشمل الوقت المقدّر للوصول التوقف عند أي نقاط طريق قبل طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
vehiclePickupToDropoffDistanceMeters |
مسافة قيادة المركبة (بالمتر) من نقطة الاستلام إلى نقطة التسليم المحدّدة في الطلب وتكون المسافة بين النقطتين فقط ولا تشمل الموقع الجغرافي للمركبة أو أي نقاط أخرى يجب زيارتها قبل أن تزور المركبة نقطة الاستلام أو نقطة التسليم. ولن تتم تعبئة القيمة إلا عند تحديد |
tripType |
مطلوبة. تمثّل هذه السمة نوع الرحلة للطلب الذي تم استخدامه لحساب الوقت المقدّر للوصول إلى نقطة الاستلام. |
vehicleTripsWaypoints[] |
يشير ذلك المصطلح إلى قائمة مرتّبة لنقاط الطريق المستخدَمة لحساب الوقت المقدَّر للوصول. تشمل القائمة الموقع الجغرافي للمركبة ونقاط استلام الرحلات النشطة للمركبة ونقاط الاستلام الواردة في الطلب. تشير القائمة الفارغة إلى تعذُّر احتساب الوقت المقدّر للوصول للمركبة. |
vehicleMatchType |
نوع مطابقة المركبة |
requestedOrderedBy |
الطلب المطلوب لترتيب تطابقات المركبات. |
orderedBy |
الطلب الفعلي الذي تم استخدامه لهذه المركبة. سيتطابق هذا عادةً مع الحقل "orderBy" في الطلب، ولكن في حالات معيّنة، مثل حدوث خطأ داخلي في الخادم، يمكن استخدام طريقة مختلفة (مثل |
النقطة الوسيطة
لوصف النقاط المتوسطة على طول مسار VehicleMatch
في SearchVehiclesResponse
. ويتم تمثيل هذا المفهوم بعلامة TripWaypoint
في جميع نقاط النهاية الأخرى.
تمثيل JSON |
---|
{
"latLng": {
object ( |
الحقول | |
---|---|
latLng |
موقع نقطة الطريق هذه. |
eta |
تمثل هذه السمة الوقت المقدَّر الذي ستصل فيه المركبة إلى نقطة الطريق هذه. طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
VehicleMatchType
نوع مطابقة المركبة
عمليات التعداد | |
---|---|
UNKNOWN |
نوع مطابقة غير معروف للمركبة |
EXCLUSIVE |
لم يتم تعيين رحلة للمركبة في الوقت الحالي ويمكنها المتابعة إلى نقطة الاستلام. |
BACK_TO_BACK |
المركبة مخصّصة حاليًا لرحلة، ولكن يمكن المتابعة إلى نقطة الاستلام بعد إكمال الرحلة التي لا تزال قيد التقدّم. تأخذ حسابات الوقت المقدر للوصول والمسافة الرحلة الحالية في الاعتبار. |
CARPOOL |
سعة المركبة كافية. |
CARPOOL_BACK_TO_BACK |
ستُكمل المركبة رحلتها الحالية النشطة قبل المتابعة إلى نقطة الاستلام. تأخذ حسابات الوقت المقدر للوصول والمسافة الرحلة الحالية في الاعتبار. |