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

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

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

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

  • روش CreateTrip(): gRPC یا REST
  • پیام CreateTripRequest: فقط gRPC

فیلدهای سفر

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

فیلدهای سفر
نام الزامی است؟ شرح
ولی بله رشته‌ای که شامل شناسه پروژه است. این شناسه باید همان شناسه‌ای باشد که در کل یکپارچگی 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;
}

قدم بعدی چیست