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

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

• راه‌اندازی 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 تنظیم شده است.
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;
}

آزمایشی: به‌عنوان یک ویژگی آزمایشی، فیلد TerminalLocation (gRPC یا REST) اکنون از استفاده از place (gRPC یا REST)، در کنار یا به‌جای LatLng پشتیبانی می‌کند.

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

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

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

توجه: هروقت intermediate_destinations را در سفری تنظیم یا به‌روزرسانی کنید، Fleet Engine مقدار 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;
}

آزمایشی: به‌عنوان یک ویژگی آزمایشی، فیلد TerminalLocation (gRPC یا REST) اکنون از استفاده از place (gRPC یا REST)، در کنار یا به‌جای LatLng پشتیبانی می‌کند.

مدیریت وضعیت سفر برای سفرهای چندمقصدی

وضعیت سفر را بااستفاده از یکی از مقادیر شمارشی 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