ایجاد سفرهای چند مقصدی

این سند نحوه ایجاد یک سفر چند مقصدی، تنظیم فیلدهای صحیح و اختصاص آن به وسیله نقلیه برای انجام را شرح می دهد. فرض می‌کند که Fleet Engine را راه‌اندازی کرده‌اید، وسایل نقلیه ایجاد کرده‌اید، یک برنامه راننده فعال و در صورت تمایل، یک برنامه مصرف‌کننده دارید. همچنین باید با سناریوهای مختلف سفر در دسترس برای سفرهای درخواستی آشنا باشید. برای آن به راهنمای مرتبط زیر مراجعه کنید:

• Fleet Engine را راه اندازی کنید
• وسیله نقلیه ایجاد کنید
• سناریوهای سفر در نمای کلی سفرهای درخواستی

اصول ایجاد سفر

این بخش جزئیات درخواست لازم برای ایجاد یک سفر در Fleet Engine را شرح می دهد. شما یک درخواست ایجاد را با استفاده از gRPC و REST صادر می کنید.

• متد CreateTrip() : gRPC یا REST
• پیام CreateTripRequest : فقط gRPC

توجه: استفاده از CreateTrip() به اعتبار حساب ممتاز ذکر شده در Fleet Engine: Service roles نیاز دارد.

فیلدهای سفر

برای ایجاد سفر در Fleet Engine از فیلدهای زیر استفاده کنید. می‌توانید از زمینه‌های مختلف برای انواع مختلف سفر استفاده کنید: سفرهای تک یا چند مقصد، پشت سر هم یا سفرهای مشترک. می‌توانید فیلدهای اختیاری را هنگام ایجاد سفر تهیه کنید، یا می‌توانید بعداً هنگام به‌روزرسانی سفر، آنها را تنظیم کنید.

زمینه های سفر

نام	مورد نیاز؟	توضیحات
پدر و مادر	بله	رشته ای که شامل شناسه پروژه است. این شناسه باید همان شناسه ای باشد که در کل ادغام Fleet Engine شما استفاده می شود، با نقش های حساب سرویس یکسان.
trip_id	بله	رشته ای که ایجاد می کنید و به طور منحصر به فردی این سفر را مشخص می کند. شناسه های سفر دارای محدودیت های خاصی هستند، همانطور که در مرجع ذکر شده است.
trip_type	بله	برای نوع سفری که ایجاد می کنید، TripType را روی مقادیر زیر تنظیم کنید: مقصد واحد : روی SHARED یا EXCLUSIVE تنظیم کنید. چند مقصد : روی EXCLUSIVE تنظیم کنید. پشت به پشت : روی EXCLUSIVE تنظیم کنید. ادغام مشترک : روی SHARED تنظیم کنید.
pickup_point	بله	نقطه مبدا سفر
مقاصد میانی	بله	فقط سفرهای چند مقصدی : فهرستی از مقاصد میانی که راننده در فاصله بین تحویل و تحویل از آنها بازدید می کند. مانند dropoff_point ، این فیلد را نیز می‌توان بعداً با تماس با UpdateTrip تنظیم کرد، اما یک سفر چند مقصد بنا به تعریف شامل مقصدهای میانی است.
وسایل نقلیه_ایستگاه های راه	بله	فقط سفرهای ادغام مشترک : این فیلد از در هم نشینی نقاط بین سفرهای متعدد پشتیبانی می کند. این شامل تمام ایستگاه های بین راهی برای وسیله نقلیه تعیین شده، و همچنین ایستگاه های حمل و نقل و تحویل برای این سفر است. می توانید این فیلد را با فراخوانی CreateTrip یا UpdateTrip تنظیم کنید. همچنین می‌توانید با تماس با UpdateVehicle نقاط بین راه خودرو را از طریق فیلد waypoints به‌روزرسانی کنید. این سرویس به دلایل حفظ حریم خصوصی، این اطلاعات را در تماس های GetTrip بر نمی گرداند.
تعداد_مسافران	خیر	تعداد مسافران در سفر.
dropoff_point	خیر	مقصد سفر
شناسه_خودرو	خیر	شناسه وسیله نقلیه اختصاص داده شده به سفر.

مثال: ایجاد یک سفر چند مقصدی

در ادامه نحوه ایجاد یک سفر چند مقصدی منحصر به فرد که دارای یک نقطه تحویل، یک نقطه تحویل و یک مقصد میانی است را نشان می دهد.

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 Engine intermediate_destinations_version در موجودیت سفر ایجاد شده پر می‌کند. شما باید این فیلد را در سیستم خود کش کنید و زمانی که بعداً intermediate_destination_index را به‌روزرسانی کردید UpdateTripRequest را ارسال کنید. این باعث می شود که مقصدهای میانی بین مشتری راننده و 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;
}

بعدش چی

• سفرهای پشت سر هم ایجاد کنید
• Driver SDK را تنظیم کنید