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

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

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

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

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

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

حقول SearchVehiclesRequest

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

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

سيناريوهات SearchVehiclesRequest

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

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

• المركبة 1: على بُعد 3500 متر من RestaurantX
• المركبة 2: على بُعد 100 متر من RestaurantX، وهي في رحلة نشطة تتضمّن عملية استلام وتسليم في الموقعَين الجغرافيَين A وB.
• المركبة 3: على بُعد 200 متر من RestaurantX مع نقطة تسليم واحدة متبقية بعيدة جدًا.
• المركبة 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