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