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

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

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

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

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

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

حقول SearchVehiclesRequest

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

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

سيناريوهات SearchVehiclesRequest

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

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

• المركبة 1: على بُعد 3,500 متر من RestaurantX.
• المركبة 2: على بُعد 100 متر من RestaurantX في رحلة نشطة مع نقطة التقاء ونقطة نزول في الموقعَين "أ" و"ب".
• المركبة 3: على بُعد 200 متر من "مطعم س"، مع تبقّي عملية توصيل واحدة بعيدة جدًا.
• المركبة 4: على بُعد 1000 متر من RestaurantX.

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

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

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

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

حقول SearchVehiclesResponse

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

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

• VehicleMatch message (gRPC)
• VehicleMatch resource (REST)

استخدام طلبات البحث الخاصة بالفلترة

تتيح السمتان 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.

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

• DeleteVehicle