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

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

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

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

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

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

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

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

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

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

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

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

حقول SearchVehiclesRequest

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

الحقل الوصف
parent مَعلمة مطلوبة. يجب أن يكون بتنسيق موفِّري التنسيق/{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.

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

أمثلة على SearchVehiclesRequest

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

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

  • المركبة 1 التي تبعد عن مطعم RestaurantX بمسافة 3500 متر.
  • المركبة 2، التي تبعد 100 متر عن مطعم RestaurantX وتوفّر رحلة نشطة مع خدمة استلام وتوصيل في الموقعين "أ" و"ب".
  • المركبة 3، التي تبعد 200 متر عن مطعم RestaurantX ولها محطة تسليم واحدة متبقية جدًا.
  • المركبة 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، بما في ذلك السمتَين Automotive_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

يوضّح المثال التالي كيفية استخدام واجهة برمجة تطبيقات SearchVehicles:

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.