كجزء من حلول الرحلات والتسليمات عند الطلب، تتيح لك إمكانات تخطيط المسار ونقله إمكانية العثور على السائقين القريبين من خلال توفير واجهة برمجة تطبيقات "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 | مَعلمة مطلوبة. يمكنك طلب المركبات بإحدى الطرق التالية:
|
العدد | مَعلمة مطلوبة. الحدّ الأقصى لعدد المركبات المطلوب إرجاعها من 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.