إنشاء رحلات مشتركة مشتركة

يوضّح هذا المستند كيفية إنشاء رحلة مشتركة، وضبط الحقول الصحيحة، وتعيينها لمركبة لتنفيذها. يفترض هذا الدليل أنّك أعددت Fleet Engine وأنشأت مركبات ولديك تطبيق سائق يعمل، ويمكنك أيضًا استخدام تطبيق مستهلك. يجب أن تكون على دراية أيضًا بسيناريوهات الرحلات المختلفة المتاحة للرحلات عند الطلب. اطّلِع على الأدلة التالية ذات الصلة بذلك:

أساسيات إنشاء الرحلات

يصف هذا القسم تفاصيل الطلب اللازمة لإنشاء رحلة في Fleet Engine. يمكنك إصدار طلب إنشاء باستخدام gRPC وREST.

  • طريقة CreateTrip(): gRPC أو REST
  • رسالة CreateTripRequest: gRPC فقط

حقول الرحلة

استخدِم الحقول التالية لإنشاء رحلة في Fleet Engine. يمكنك استخدام حقول مختلفة لأنواع الرحلات المختلفة: رحلات ذات وجهة واحدة أو وجهات متعددة، أو رحلات متتالية، أو رحلات مشتركة. يمكنك توفير الحقول الاختيارية عند إنشاء الرحلة، أو يمكنك ضبطها لاحقًا عند تعديل الرحلة.

حقول الرحلة
الاسم مطلوب؟ الوصف
parent نعم سلسلة تتضمّن رقم تعريف المشروع يجب أن يكون هذا المعرّف هو نفسه المعرّف المستخدَم في عملية دمج Fleet Engine بالكامل، مع أدوار حساب الخدمة نفسها.
trip_id نعم سلسلة تنشئها لتحديد هذه الرحلة بشكل فريد. تخضع معرّفات الرحلات لقيود معيّنة، كما هو موضّح في المرجع.
trip_type نعم اضبط TripType على القيم التالية لنوع الرحلة التي تنشئها:
  • وجهة واحدة: اضبط القيمة على SHARED أو EXCLUSIVE.
  • وجهات متعددة: اضبط القيمة على EXCLUSIVE.
  • متتالية: اضبطها على EXCLUSIVE.
  • التجميع المشترَك: تم ضبطه على SHARED.
pickup_point نعم نقطة انطلاق الرحلة
الوجهات المتوسطة نعم

الرحلات المتعدّدة الوجهات فقط: قائمة الوجهات الوسيطة التي يزورها السائق بين نقطة الانطلاق ونقطة الوصول. كما هو الحال مع dropoff_point، يمكن أيضًا ضبط هذا الحقل لاحقًا من خلال طلب UpdateTrip، ولكن الرحلة المتعدّدة الوجهات تحتوي بطبيعتها على وجهات وسيطة.
vehicle_waypoints نعم

الرحلات المشتركة فقط: يتيح هذا الحقل تداخل نقاط المسار من رحلات متعددة. وتحتوي على جميع النقاط المتبقية على المسار للمركبة المحدّدة، بالإضافة إلى نقاط الركوب والنزول لهذه الرحلة. يمكنك ضبط هذا الحقل من خلال استدعاء CreateTrip أو UpdateTrip. يمكنك أيضًا تعديل نقاط مسار المركبة من خلال الحقل waypoints من خلال طلب إلى UpdateVehicle. لا تعرض الخدمة هذه المعلومات في مكالمات GetTrip لأسباب تتعلق بالخصوصية.
number_of_passengers لا عدد الركاب في الرحلة
dropoff_point لا وجهة الرحلة
vehicle_id لا رقم تعريف المركبة المخصّصة للرحلة

مثال: إنشاء رحلة مشتركة مع ركاب آخرين

يوضّح نموذج دمج الخلفية التالي كيفية إنشاء رحلة وتعيينها لمركبة كرحلة مشتركة.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

تعديل الرحلات المشتركة التي يتم تجميعها

يجب تعيين أي رحلة تم إنشاؤها في Fleet Engine إلى مركبة لكي يتمكّن Fleet Engine من احتساب الأوقات المقدَّرة للوصول وتتبُّعها. يمكنك إجراء ذلك أثناء إنشاء الرحلة أو لاحقًا عند تعديلها.

بالنسبة إلى الرحلات المشتركة، يجب تحديد ترتيب للنقاط على المسار التي لم تتم زيارتها في مجموعة النقاط على المسار الخاصة بالمركبة (Trip.vehicle_waypoints). يستخدم Fleet Engine هذه القائمة لتعديل النقاط على المسار تلقائيًا لجميع الرحلات في المجموعة المشتركة.

على سبيل المثال، لنفترض أنّ هناك رحلتَين مشترَكتَين، الرحلة "أ" والرحلة "ب":

  • الرحلة "أ" في طريقها إلى موقع النزول.
  • بعد ذلك، تتم إضافة الرحلة "ب" إلى المركبة نفسها.

في UpdateTripRequest واحدة للرحلة "ب"، يمكنك ضبط vehicleId، وضبط Trip.vehicle_waypoints أيضًا على الترتيب الأمثل للنقاط على المسار: نقطة الالتقاء "ب" → نقطة النزول "أ" → نقطة النزول "ب".

  • يؤدي استدعاء getVehicle() إلى عرض remainingWaypoints التي تحتوي على:
    B استلام ← A توصيل ← B توصيل.
  • تعرض دالة رد الاتصال getTrip() أو onTripRemainingWaypointsUpdated لـ الرحلة "أ" remainingWaypoints التي تحتوي على:
    نقطة استلام "ب" ← نقطة توصيل "أ".
  • إما getTrip() أو دالة الاستدعاء onTripRemainingWaypointsUpdated للرحلة "ب" تعرض remainingWaypoints التي تحتوي على:
    نقطة الانطلاق "ب" ← نقطة النزول "أ" ← نقطة النزول "ب".

مثال

يوضّح نموذج دمج الخلفية التالي كيفية تعديل رحلة باستخدام معرّف المركبة ونقاط المسار لرحلتَين مشتركتَين.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

الخطوات التالية