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

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

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

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

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

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

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

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

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

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

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

• يمكنك إنشاء SearchVehiclesRequest استنادًا إلى المهمة المطلوب إسنادها.
• طلب واجهة برمجة تطبيقات SearchVehicles (vehicleService.searchVehicles) مع الطلب المنشأة.
• معالجة 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.

يُرجى مراجعة المستندات المرجعية للاطّلاع على المجموعة الكاملة 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

يوضّح المثال التالي كيفية استخدام واجهة برمجة تطبيقات 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.