إنشاء رحلات إلى وجهات متعددة

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

مثال: إنشاء رحلة متعددة الوجهات

يوضّح المثال التالي كيفية إنشاء رحلة حصرية متعددة الوجهات تتضمّن نقطة استلام ونقطة توصيل ووجهة وسيطة واحدة.

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;
}

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