البحث عن مركبات

كجزء من خدمة الرحلات عند الطلب، يمكنك العثور على المركبات القريبة باستخدام طريقة SearchVehicles.

تتيح لك طريقة SearchVehicles العثور على المركبات القريبة المتاحة في تطبيقك المتوافق مع الأجهزة الجوّالة، والتي تكون الأنسب لرحلة معيّنة أو طلب تسليم. تعرض واجهة برمجة التطبيقات SearchVehicles قائمة بالمركبات مرتّبة حسب الأولوية، وتتطابق سماتها مع سمات الرحلة المطلوبة. يتم الترتيب حسب خيارك من وقت الوصول المقدَّر أو المسافة أو المسافة بخط مستقيم من نقطة الاستلام.

سمات البحث سمات المركبات
  • مواقع استلام الطلب وتسليمه
  • أنواع المركبات والرحلات المطلوبة
  • السعة المطلوبة
  • سمات المطابقة المطلوبة الأخرى
  • آخر موقع جغرافي معروف لمركبة
  • حالة المركبة أو نوعها أو سعتها
  • سمات مخصّصة أخرى

استخدام طريقة SearchVehicles

لاستخدام SearchVehicles، اتّبِع هذه العملية العامة:

  1. أنشئ SearchVehiclesRequest استنادًا إلى الرحلة التي سيتم تعيينها.
  2. استدعِ واجهة برمجة التطبيقات SearchVehicles (vehicleService.searchVehicles) باستخدام الطلب الذي تم إنشاؤه.
  3. عالِج SearchVehicleResponse الذي يتم عرضه من واجهة برمجة التطبيقات.

حقول SearchVehiclesRequest

استخدِم حقول السمات المطلوبة التالية لإنشاء SearchVehiclesRequest:

الحقل الوصف
parent مَعلمة مطلوبة. يجب أن يكون التنسيق providers/{provider}. يجب أن يكون مقدّم الخدمة هو رقم تعريف مشروع Google Cloud الذي ينتمي إليه حساب الخدمة الذي يجري هذا الاتصال.
vehicle_types مَعلمة مطلوبة. أنواع المركبات المطلوبة، إما AUTO أو TWO_WHEELER أو TAXI أو TRUCK أو BICYCLE أو PEDESTRIAN.
trip_types مَعلمة مطلوبة. إما EXCLUSIVE (رحلة نشطة واحدة في كل مرة لكل سائق) أو SHARED (رحلة واحدة أو عدة رحلات في كل مرة لكل سائق).
minimum_capacity مَعلمة مطلوبة. الحد الأدنى للسعة المتبقية للمركبة لرحلة جديدة، إما للركاب أو عمليات التسليم.
pickup_point مَعلمة مطلوبة. موقع استلام الطلب للرحلة بإحداثيات خطوط الطول والعرض
dropoff_point اختياريّ. موقع تسليم الطلب للرحلة بإحداثيات خطوط الطول والعرض يكون هذا الحقل مطلوبًا إذا كان trip_types يحتوي على TripType.SHARED.
pickup_radius_meters مَعلمة مطلوبة. نصف قطر منطقة البحث عن المركبات بالمتر من نقطة استلام الطلب
order_by مَعلمة مطلوبة. ترتيب المركبات حسب أحد الخيارات التالية:
  • PICKUP_POINT_ETA، وهو الوقت المقدر للوصول للمركبة في نقطة استلام الطلب.
  • PICKUP_POINT_DISTANCE، وهي المسافة بين المركبة ونقطة استلام الطلب
  • DROPOFF_POINT_ETA، وهو الوقت المقدر للوصول للمركبة لإكمال الرحلة في نقطة تسليم الطلب
  • PICKUP_POINT_STRAIGHT_DISTANCE، وهي المسافة بخط مستقيم (غير مدرَجة في المسار) بين المركبة ونقطة استلام الطلب
count مَعلمة مطلوبة. الحد الأقصى لعدد المركبات التي سيتم عرضها، ويتراوح بين 1 و50
filter اختياريّ. طلب فلتر لتطبيقه عند البحث عن المركبات
maximum_staleness اختياريّ. يقتصر البحث على المركبات التي أرسلت تحديثات الموقع الجغرافي إلى Fleet Engine خلال المدة المحدّدة فقط. إذا لم يتم ضبط هذا الحقل، يستخدم الخادم خمس دقائق كقيمة تلقائية.

يُرجى الرجوع إلى المستندات المرجعية للاطّلاع على المجموعة الكاملة من SearchVehicleRequest.

سيناريوهات SearchVehiclesRequest

يعرض هذا القسم أمثلة على كيفية إنشاء SearchVehiclesRequest.

على سبيل المثال، لنفترض أنّ أحد العملاء يريد استلامه من مطعم RestaurantX، ولديك أربع مركبات:

  • المركبة 1: على بُعد 3500 متر من مطعم RestaurantX.
  • المركبة 2: على بُعد 100 متر من مطعم RestaurantX، ولديها رحلة نشطة مع استلام وتسليم في الموقعَين A وB
  • المركبة 3: على بُعد 200 متر من مطعم RestaurantX، ولديها عملية تسليم واحدة متبقية بعيدة جدًا
  • المركبة 4: على بُعد 1000 متر من مطعم RestaurantX

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

عرض المركبة 4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

عرض المركبتَين 3 و4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

عرض المركبات 2 و3 و4

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL

حقول SearchVehiclesResponse

يتألف SearchVehiclesResponse من قائمة بكيانات VehicleMatch، مرتّبة حسب سمة order_by المحدّدة في SearchVehiclesRequest. يحتوي كل كيان VehicleMatch على الحقول التالية:

الحقل الوصف
vehicle كائن Vehicle، بما في ذلك vehicle_id وسمات Vehicle
vehicle_pickup_eta الوقت المقدر للوصول للمركبة في موقع استلام الطلب إذا تم تعيين هذه الرحلة للمركبة الآن
vehicle_pickup_distance_meter المسافة بالمتر بين المركبة وموقع استلام الطلب للرحلة الجديدة
vehicle_pickup_straight_line_distance_meter المسافة بخط مستقيم بالمتر بين المركبة وموقع استلام الطلب للرحلة الجديدة
vehicle_dropoff_eta وقت الوصول المقدَّر للمركبة في موقع تسليم الطلب إذا تم تعيين هذه الرحلة للمركبة الآن
vehicle_trips_waypoints قائمة بنقاط الطريق المتبقية، بما في ذلك نقاط استلام الطلب وتسليمه، للرحلات النشطة المعيّنة حاليًا للمركبة
vehicle_match_type نوع رحلة المركبة، إما EXCLUSIVE أو BACK_TO_BACK أو CARPOOL أو CARPOOL_BACK_TO_BACK

للاطّلاع على قائمة كاملة بحقول VehicleMatch، يُرجى مراجعة:

استخدام طلبات الفلتر

تتيح الطريقتان SearchVehicles وListVehicles إمكانية الفلترة حسب سمات المركبة باستخدام طلب فلتر.

لا تتيح طلبات الفلتر سوى الفلترة حسب السمات المخصّصة للمركبات، ولا يمكن استخدامها للحقول الأخرى. عند استخدامها في عملية بحث تتضمّن معايير حقول أخرى، مثل minimum_capacity أو vehicle_types، تعمل طلبات الفلتر كعبارة AND.

على سبيل المثال، إذا كنت تبحث عن مركبة بسعة لا تقل عن 6 ركاب وتفلتر attributes مثل "مسموح بالحيوانات الأليفة"، لن تعرض المعايير سوى المركبات التي تسمح بالحيوانات الأليفة ويمكنها استيعاب 6 ركاب على الأقل.

بالنسبة إلى بنية طلبات الفلتر، يُرجى الاطّلاع على AIP-160 للحصول على أمثلة. لمعرفة تفاصيل إنشاء سمات المركبة، يُرجى الاطّلاع على حقل سمات المركبة في دليل تعديل حقول المركبة.

مثال على SearchVehicles

يوضّح المثال التالي كيفية استخدام واجهة برمجة التطبيقات SearchVehicles باستخدام مكتبة Java gRPC. للاطّلاع على قائمة كاملة باللغات المتاحة، يُرجى مراجعة مكتبات العملاء لخدمات الرحلات عند الطلب.

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jkt Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(Category.AUTO).build())
    .setCurrentTripsPresent(CurrentTripsPresent.ANY)
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .build();

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

List<VehicleMatch> vehicleMatches =
    searchVehicleResponse.getMatchesList();

// Each VehicleMatch contains a Vehicle entity and information about the
// distance and ETA to the pickup point and drop-off point.

الخطوات التالية