جارٍ البحث عن سائقين قريبين

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

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

يمكن أن تتضمن سمات المهمة ما يلي:

  • مواقع استلام الطلبات وتسليمها
  • أنواع المركبات والرحلات المطلوبة
  • السعة المطلوبة
  • السمات المطابقة الأخرى المطلوبة

يمكن أن تشمل سمات المركبة ما يلي:

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

يتم ترتيب الترتيب حسب اختيارك إمّا الوقت المقدّر للوصول أو المسافة أو مسافة الخط المستقيم من نقطة الاستلام.

تجدر الإشارة إلى أنّه يجب أن يكون لديك امتيازات "المستخدم المتميّز في Fleet Engine" أو "مستخدم حزمة تطوير البرامج (SDK) للمستهلك" في خدمة Fleet Engine لتتمكّن من استخدام SearchVehicles API. لمزيد من المعلومات، راجع المصادقة والتفويض.

استخدام SearchVehicles API

لاستخدام واجهة برمجة التطبيقات SearchVehicles:

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

حقول SearchVehiclesRequest

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

الحقل الوصف
parent مَعلمة مطلوبة. يجب أن يكون بالتنسيق موفِّري الخدمة/{provider}. يجب أن يكون مقدّم الخدمة هو رقم تعريف المشروع (على سبيل المثال، sample-cloud-project) في "مشروع Google Cloud" الذي يكون حساب الخدمة الذي يجري هذا الطلب عضوًا فيه.
vehicle_types مَعلمة مطلوبة. أنواع المركبات المطلوبة، إما Auto (سيارة) أو TWO_WHEELER أو "سيارة أجرة" أو "شاحنة" أو "دراجة" أو "مشاة".
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

يمكنك الرجوع إلى المستندات المرجعية للاطّلاع على المجموعة الكاملة من SearchVehicleRequestfields.

أمثلة على SearchVehiclesRequest

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

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

  • المركبة 1 التي تبعد 3500 متر عن RestaurantX.
  • المركبة 2، التي تقع على بُعد 100 متر من RestaurantX، وتشمل رحلة نشطة مع خدمة استلام الطلب وتوصيله في الموقعين A وB.
  • Vehicle 3، التي تقع على بُعد 200 متر من RestaurantX، ويتبقى لديه نقطة هبوط واحدة على بُعد مسافة بعيدة جدًا.
  • Vehicle 4 (المركبة 4) التي يبعُد مسافة 1000 متر عن RestaurantX.

تعرض السمة SearchVehiclesRequest التالية المركبة 4:

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

تعرض السمة SearchVehiclesRequest التالية المركبة 3 و4:

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

تعرض السمة SearchVehiclesRequest التالية المركبة 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، بما في ذلك سمتَي bike_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.

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

يوضّح المثال التالي كيفية استخدام SearchVehicles API:

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.