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

كجزء من خدمة الرحلات عند الطلب في "منصة التنقّل"، يمكنك العثور على المركبات القريبة باستخدام طريقة 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.

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

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

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

إرجاع المركبة 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.

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