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

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

• إعداد Fleet Engine
• إنشاء مركبة
• سيناريوهات الرحلات في النظرة العامة على الرحلات عند الطلب

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

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

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

ملاحظة: يتطلب استخدام CreateTrip() بيانات اعتماد الحساب المميّز. تم ذكرها في Fleet Engine: أدوار حساب الخدمة.

حقول الرحلة

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

حقول الرحلة

الاسم	مطلوب؟	الوصف
أحد الوالدَين	نعم	سلسلة تحتوي على رقم تعريف المشروع يجب أن يكون هذا المعرّف هو المعرّف نفسه المستخدَم في عملية دمج Fleet Engine بالكامل، مع أدوار حساب الخدمة نفسها.
trip_id	نعم	سلسلة تُنشئها وتُعرِّف هذه الرحلة بشكلٍ فريد تفرض معرّفات الرحلات بعض القيود، كما هو موضّح في المرجع.
trip_type	نعم	اضبط TripType على القيم التالية لنوع الرحلة التي تنشئها: وجهة واحدة: اضبط القيمة على SHARED أو EXCLUSIVE. وجهات متعددة: اضبط القيمة على EXCLUSIVE. تحول إلى الخلف: اضبط على EXCLUSIVE. التجميع المشترك: اضبط على SHARED.
نقطة_الاستلام	نعم	نقطة المنشأ للرحلة
الوجهات المتوسطة المستوى	نعم	الرحلات متعددة الوجهات فقط: قائمة الوجهات المتوسطة التي يزورها السائق للاستلام والتسليم. وكما هو الحال مع dropoff_point، فإن هذا الحقل يمكن أيضًا تعيينها لاحقًا عن طريق طلب UpdateTrip، لكن الوجهة متعددة الوجهات تحتوي "الرحلة حسب التعريف" على وجهات متوسطة.
نقاط_الطريق_للمركبة	نعم	رحلات التجميع المشترك فقط: يتيح هذا الحقل دمج نقاط الطريق من رحلات متعددة. يحتوي هذا الملف على جميع نقاط التوقف المتبقية للمركبة المحدّدة، بالإضافة إلى نقاط التوقف لتحميل الركاب وإيقافهم في هذه الرحلة. يمكنك ضبط هذا الحقل من خلال الاتصال برقم 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 من تتبُّعها. المركبة على طول مسارها. للحصول على تفاصيل حول تعديل رحلة، يمكنك الاطّلاع على تعديل الرحلات وإدارة حالتها

في حال عدم تحديد وجهة لإنزال أو وجهات وسيطة عند إنشاء الرحلة، يمكنك دائمًا القيام بذلك في هذه المرحلة.

ملاحظة: عند ضبط أو تعديل intermediate_destinations في رحلة، يتم تطبيق Fleet. يملأ المحرّك بيانات intermediate_destinations_version في الرحلة التي تم إنشاؤها. . يجب تخزين هذا الحقل مؤقتًا في نظامك وإدخال UpdateTripRequest عند تعديل intermediate_destination_index لاحقًا. يعمل ذلك على إبقاء الوجهات المتوسطة متزامنة بين برنامج السائق 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

ملاحظة: يجب أن تمر الرحلة بكل من ENROUTE_TO_INTERMEDIATE_DESTINATION وARRIVED_AT_INTERMEDIATE_DESTINATION مرة واحدة لكل وجهة وسيطة.

مثال على رحلة مع وجهات متوسطة

يوضح ما يلي كيفية إنشاء رحلة متعددة الوجهات اجتازت وهي الآن في طريقها إلى أول وجهة متوسطة لها.

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

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

• إنشاء رحلات متعاقبة
• إعداد حزمة تطوير البرامج (SDK) لبرنامج التشغيل