ایجاد سفرهای استخری مشترک

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

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

این بخش جزئیات درخواست لازم برای ایجاد سفر در 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 نه شناسه وسیله نقلیه اختصاص‌یافته به سفر.

مثال: ایجاد سفر استخری مشترک

نمونه ادغام زیرینه نحوه ایجاد سفر و اختصاص آن به وسیله نقلیه به‌عنوان سفر مشترک را نشان می‌دهد.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

به‌روزرسانی سفرهای استخر مشترک

هر سفری که در Fleet Engine ایجاد می‌شود باید به خودرویی اختصاص داده شود تا Fleet Engine بتواند «زمان‌های تخمینی رسیدن» سفر را محاسبه کند و آن را ردیابی کند. می‌توانید این کار را درطول ایجاد سفر یا بعداً هنگام به‌روزرسانی سفر انجام دهید.

برای سفرهای اشتراکی، باید ترتیبی برای نقطه‌مسیرهای بازدیدنشده در مجموعه نقطه‌مسیرهای خودروی سفر (Trip.vehicle_waypoints) مشخص کنید. Fleet Engine از این فهرست برای به‌روزرسانی خودکار نقطه‌مسیرهای سفر برای همه سفرهای موجود در اشتراک استفاده می‌کند.

برای مثال، دو سفر هم‌پیمایی سفر الف و سفر ب را درنظر بگیرید:

  • سفر A در مسیر مکان پیاده شدن است.
  • سپس سفر B به همان خودرو اضافه می‌شود.

در UpdateTripRequest برای سفر B، vehicleId را تنظیم می‌کنید و همچنین Trip.vehicle_waypoints را روی ترتیب بهینه ایستگاه‌های بین راه تنظیم می‌کنید: B محل سوار شدن → A محل پیاده شدن → B محل پیاده شدن.

  • با فراخوانی getVehicle()، remainingWaypoints برگردانده می‌شود که حاوی موارد زیر است:
    B سوار کردن ← A پیاده کردن ← B پیاده کردن.
  • یا getTrip() یا onTripRemainingWaypointsUpdated برگشت تماس برای سفر A remainingWaypoints برمی‌گرداند که شامل موارد زیر است:
    B تحویل گرفتن → A پیاده کردن.
  • یا getTrip() یا onTripRemainingWaypointsUpdated برگشت تماس برای سفر B remainingWaypoints برمی‌گرداند که شامل این موارد است:
    B تحویل گرفتن → A پیاده کردن → B پیاده کردن.

مثال

نمونه ادغام با پسین زیر نشان می‌دهد که چگونه می‌توان سفری را با شناسه خودرو و نقاط‌مسیر برای دو سفر با استخر مشترک به‌روز کرد.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

قدم بعدی چیست