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

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

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

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

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

زمینه‌های سفر

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

زمینه‌های سفر
نام الزامی است؟ توضیحات
والدین بله رشته‌ای که شامل شناسه پروژه است. این شناسه باید همان شناسه‌ای باشد که در کل یکپارچه‌سازی Fleet Engine شما، با همان نقش‌های حساب سرویس، استفاده می‌شود.
شناسه سفر بله رشته‌ای که شما ایجاد می‌کنید و به طور منحصر به فرد این سفر را مشخص می‌کند. شناسه‌های سفر محدودیت‌های خاصی دارند، همانطور که در مرجع ذکر شده است.
نوع_سفر بله برای نوع سفری که ایجاد می‌کنید، TripType را روی مقادیر زیر تنظیم کنید:
  • مقصد واحد : روی SHARED یا EXCLUSIVE تنظیم کنید.
  • چند مقصدی : روی EXCLUSIVE تنظیم کنید.
  • پشت سر هم : روی EXCLUSIVE تنظیم کنید.
  • اشتراک‌گذاری مشترک : روی SHARED تنظیم شود.
نقطه برداشت بله نقطه مبدا سفر.
مقاصد میانی بله

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

نقاط مسیر وسیله نقلیه بله

فقط سفرهای اشتراکی : این فیلد از ادغام نقاط مسیر از چندین سفر پشتیبانی می‌کند. این فیلد شامل تمام نقاط مسیر باقی‌مانده برای وسیله نقلیه اختصاص داده شده و همچنین نقاط مسیر سوار و پیاده شده برای این سفر است. می‌توانید این فیلد را با فراخوانی CreateTrip یا UpdateTrip تنظیم کنید. همچنین می‌توانید نقاط مسیر وسیله نقلیه را از طریق فیلد waypoints با فراخوانی UpdateVehicle به‌روزرسانی کنید. این سرویس به دلایل حریم خصوصی، این اطلاعات را در فراخوانی‌های GetTrip برنمی‌گرداند.

تعداد_مسافران خیر تعداد مسافران در سفر.
نقطه رهاسازی خیر مقصد سفر.
شناسه وسیله نقلیه خیر شماره شناسایی وسیله نقلیه اختصاص داده شده به سفر.

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

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

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

به‌روزرسانی یک سفر چند مقصدی

شما باید سفر را با شناسه وسیله نقلیه پیکربندی کنید تا موتور ناوگان بتواند وسیله نقلیه را در طول مسیر خود ردیابی کند. برای جزئیات بیشتر در مورد به‌روزرسانی یک سفر، به «به‌روزرسانی سفرها و مدیریت وضعیت آنها» مراجعه کنید.

اگر هنگام ایجاد سفر، مقصد پیاده شدن یا مقصد میانی را مشخص نکرده‌اید، می‌توانید در این مرحله این کار را انجام دهید.

نمونه به‌روزرسانی سفر

موارد زیر نحوه به‌روزرسانی یک سفر برای افزودن لیستی از مقصدهای میانی و تنظیم شناسه وسیله نقلیه را نشان می‌دهد.

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

قدم بعدی چیست؟