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

يصف هذا المستند كيفية إنشاء رحلة مشتركة، وتحديد الحقول الصحيحة، وتعيينها لمركبة لتنفيذها. يفترض هذا المستند أنّك أعددت 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 نعم نقطة انطلاق الرحلة
Intermediate destinations نعم

الرحلات المتعددة الوجهات فقط: قائمة بالوجهات الوسيطة التي يزورها السائق بين نقطة الانطلاق ونقطة الوصول. على غرار 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 التي تحتوي على:
    نقطة انطلاق الرحلة ب ← نقطة وصول الرحلة أ ← نقطة وصول الرحلة ب.
  • عند استدعاء 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;
}

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