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

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

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

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

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

لاستخدام SearchVehicles، يُرجى اتّباع العملية العامة التالية:

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

حقول SearchVehiclesRequest

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

الحقل الوصف
عنصر رئيسي مَعلمة مطلوبة. يجب أن يكون بتنسيق موفِّري التنسيق/{provider}. يجب أن يكون مقدّم الخدمة هو رقم تعريف المشروع الخاص بالمشروع على Google Cloud الذي ينتمي إليه حساب الخدمة الذي يجري هذه المكالمة.
vehicle_types مَعلمة مطلوبة. أنواع المركبات المطلوبة، إما OUT أو 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.

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

  • المركبة 1: على بُعد 3500 متر من مطعم RestaurantX.
  • المركبة 2: على بُعد 100 متر من مطعم RestaurantX مع رحلة نشطة مع خدمة استلام الطلب واذهب إلى الموقعين "أ" و"ب".
  • المركبة 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_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 API من خلال مكتبة 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.

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