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

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

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

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

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

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

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

حقول SearchVehiclesRequest

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

الحقل الوصف
عنصر رئيسي مَعلمة مطلوبة. يجب أن يكون بالتنسيق providers/{provider}. يجب أن يكون مقدّم الخدمة هو رقم تعريف مشروع Google Cloud الذي يكون حساب الخدمة الذي يجري هذا الطلب عضوًا فيه.
vehicle_types مَعلمة مطلوبة. أنواع المركبات المطلوبة، إما AUTO أو TWO_WHEELER أو TAXI أو TRUCK أو BICYCLE أو PEDESTRIAN
trip_types مَعلمة مطلوبة. إما حصرية (رحلة نشطة واحدة في كل مرة لكل سائق) أو مشتركة (رحلة واحدة أو عدّة رحلات في كل مرة لكل سائق).
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، وهي المسافة المستقيمة (وليس على المسار) بين المركبة ونقطة الاستلام.
العدد مَعلمة مطلوبة. الحد الأقصى لعدد المركبات التي سيتم عرضها من 1 إلى 50.
تصفية Optional. طلب بحث فلتر لتطبيقه عند البحث عن المركبات

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

سيناريوهات SearchVehiclesRequest

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

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

  • المركبة 1: على بُعد 3500 متر من مطعم "س"
  • المركبة 2: على بُعد 100 متر من مطعم "س"، وهي في رحلة نشِطة تشمل عملية نقل وإرجاع في الموقعَين "أ" و"ب".
  • المركبة 3: على بُعد 200 متر من مطعم "س"، مع عملية تسليم واحدة متبقّية في مكان بعيد جدًا.
  • المركبة 4: على بُعد 1,000 متر من مطعم "س"

يعرض الجدول التالي طلبات مختلفة حسب المركبة التي يتم عرضها.

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

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