يوضّح هذا المستند كيفية إنشاء رحلة تتضمّن وجهات متعدّدة، وضبط الحقول الصحيحة، وتحديد مركبة لتنفيذ الرحلة. ويفترض هذا الدليل أنّك قد أعددت Fleet Engine، وأنشأت مركبات، ولديك تطبيق يعمل للسائقين، ويمكنك أيضًا إنشاء تطبيق للمستهلكين. يجب أيضًا أن تكون على دراية بمختلف سيناريوهات الرحلات المتاحة للرحلات عند الطلب. يمكنك الاطّلاع على الأدلة ذات الصلة التالية:
- إعداد Fleet Engine
- إنشاء مركبة
- سيناريوهات الرحلات في النظرة العامة على الرحلات عند الطلب
أساسيات إنشاء الرحلات
يوضّح هذا القسم تفاصيل الطلب اللازمة لإنشاء رحلة في Fleet Engine. يمكنك إصدار طلب إنشاء باستخدام gRPC أو REST.
حقول الرحلة
استخدِم الحقول التالية لإنشاء رحلة في Fleet Engine. يمكنك استخدام حقول مختلفة لأنواع الرحلات المختلفة: رحلة إلى وجهة واحدة أو وجهات متعددة، أو رحلة متتالية، أو رحلة مشتركة. يمكنك تقديم الحقول الاختيارية عند إنشاء الرحلة، أو يمكنك ضبطها لاحقًا عند تعديل الرحلة.
الاسم | مطلوب؟ | الوصف |
---|---|---|
parent | نعم | سلسلة تتضمّن رقم تعريف المشروع يجب أن يكون هذا المعرّف هو المعرّف نفسه المستخدَم في عملية دمج Fleet Engine بالكامل، مع أدوار حساب الخدمة نفسها. |
trip_id | نعم | سلسلة تنشئها وتحدّد هذه الرحلة بشكل فريد. تخضع معرّفات الرحلات لقيود معيّنة، كما هو موضّح في المرجع. |
trip_type | نعم | اضبط قيمة TripType على القيم التالية لنوع الرحلة الذي تريد إنشاءه:
|
pickup_point | نعم | نقطة انطلاق الرحلة |
الوجهات الوسيطة | نعم | الرحلات المتعددة الوجهات فقط: قائمة بالوجهات الوسيطة التي يتوقف فيها السائق بين نقطتَي الاستلام والتسليم. كما هو الحال مع |
vehicle_waypoints | نعم | الرحلات التي تتضمّن مشاركة الركوب فقط: يتيح هذا الحقل دمج نقاط الطريق من رحلات متعددة.
يحتوي على جميع نقاط الطريق المتبقية للمركبة المخصّصة، بالإضافة إلى نقاط طريق الاستلام والتسليم لهذه الرحلة. يمكنك ضبط هذا الحقل
من خلال استدعاء |
number_of_passengers | لا | عدد الركاب في الرحلة |
dropoff_point | لا | وجهة الرحلة |
vehicle_id | لا | معرّف المركبة المخصّصة للرحلة |
مثال: إنشاء رحلة تتضمّن وجهات متعدّدة
يوضّح المثال التالي كيفية إنشاء رحلة حصرية متعدّدة الوجهات تتضمّن نقطة استلام ونقطة تسليم ووجهة وسيطة واحدة.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip initial settings.
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE)
.setPickupPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder()
.setLatitude(-6.195139).setLongitude(106.820826)))
.setNumberOfPassengers(1)
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder()
.setLatitude(-6.1275).setLongitude(106.6537)))
// Add the list of intermediate destinations.
.addAllIntermediateDestinations(
ImmutableList.of(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder()
.setLatitude(-6.195139).setLongitude(106.820826)).build()))
.build();
// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
.setParent(parent)
.setTripId(TRIP_ID) // Trip ID assigned by the Provider server.
.setTrip(trip) // Initial state is NEW.
.build();
// Error handling.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS: // Trip already exists.
break;
case PERMISSION_DENIED:
break;
}
return;
}
تعديل رحلة تتضمّن وجهات متعدّدة
يجب ضبط الرحلة باستخدام رقم تعريف المركبة حتى يتمكّن Fleet Engine من تتبُّع المركبة على طول مسارها. للحصول على تفاصيل حول تعديل رحلة، يُرجى الاطّلاع على تعديل الرحلات وإدارة حالتها.
إذا لم تحدّد نقاط توقّف أو وجهات وسيطة عند إنشاء الرحلة، يمكنك إجراء ذلك في هذه المرحلة.
مثال على تعديل رحلة
يوضّح المثال التالي كيفية تعديل رحلة لإضافة قائمة بوجهات وسيطة وتحديد معرّف مركبة.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// The trip settings to be updated.
Trip trip = Trip.newBuilder()
// Add the list of intermediate destinations.
.addAllIntermediateDestinations(
ImmutableList.of(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder()
.setLatitude(-6.195139).setLongitude(106.820826)).build()))
.setVehicleId("8241890")
.build();
// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("intermediate_destinations")
.addPaths("vehicle_id")
.build())
.build();
// Error handling.
try {
Trip updatedTrip =
tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // The trip doesn't exist.
break;
case PERMISSION_DENIED:
break;
}
return;
}
إدارة حالة الرحلة للرحلات المتعددة الوجهات
يمكنك تحديد حالة الرحلة باستخدام إحدى قيم التعداد TripStatus
. عندما تتغيّر حالة رحلة، مثلاً من ENROUTE_TO_PICKUP
إلى ARRIVED_AT_PICKUP
، عليك تعديل حالة الرحلة في Fleet Engine. تبدأ حالة الرحلة دائمًا بالقيمة NEW
، وتنتهي بالقيمة COMPLETE
أو CANCELED
.
بالنسبة إلى الرحلات المتعددة الوجهات، بالإضافة إلى تعديل حالة الرحلة كما تفعل في الرحلات ذات الوجهة الواحدة، عليك أيضًا تعديل ما يلي في كل مرة تصل فيها مركبتك إلى وجهة وسيطة:
intermediateDestinationIndex
intermediateDestinationsVersion
لإجراء ذلك، استخدِم القيم التالية من التعداد TripStatus
.
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
مثال على رحلة تتضمّن وجهات وسيطة
يوضّح المثال التالي كيفية إنشاء رحلة متعدّدة الوجهات تجاوزت نقطة الاستلام، وهي الآن في طريقها إلى الوجهة الوسيطة الأولى.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// The trip settings to be updated.
Trip trip = Trip.newBuilder()
// Trip status cannot return to a previous state once it has passed.
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enroute to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// You must provide an intermediate_destinations_version to ensure that you
// have the same intermediate destinations list as the Fleet Engine.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the update mask.
.build())
.build();
// Error handling.
try {
Trip updatedTrip =
tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // The trip doesn't exist.
break;
case FAILED_PRECONDITION: // Either the trip status is invalid, or the
// intermediate_destinations_version doesn't
// match Fleet Engine's.
break;
case PERMISSION_DENIED:
break;
}
return;
}