این سند نحوه ایجاد سفر چندمقصدی، تنظیم فیلدهای صحیح، و واگذاری آن به خودرو برای انجام را شرح میدهد. فرض میشود که «موتور ناوگان» را راهاندازی کردهاید، خودروها را ایجاد کردهاید، برنامه راننده کاری دارید، و بهصورت اختیاری، برنامه مصرفکننده دارید. همچنین باید با سناریوهای مختلف سفر که برای سفرهای درخواستی دردسترس است آشنا باشید. برای این کار، راهنماهای مرتبط زیر را ببینید:
- راهاندازی Fleet Engine
- ایجاد خودرو
- سناریوهای سفر در نمای کلی سفرهای درخواستی
اصول اولیه ایجاد سفر
این بخش جزئیات درخواست لازم برای ایجاد سفر در Fleet Engine را شرح میدهد. درخواست ایجاد را بااستفاده از gRPC یا REST صادر میکنید.
فیلدهای سفر
از فیلدهای زیر برای ایجاد سفر در Fleet Engine استفاده کنید. میتوانید از فیلدهای مختلف برای انواع مختلف سفرها استفاده کنید: تکمقصد یا چندمقصد، پشتسرهم، یا سفرهای استخری مشترک. میتوانید فیلدهای اختیاری را هنگام ایجاد سفر ارائه دهید یا میتوانید آنها را بعداً هنگام بهروزرسانی سفر تنظیم کنید.
| نام | الزامی است؟ | شرح |
|---|---|---|
| ولی | بله | رشتهای که شامل شناسه پروژه است. این شناسه باید همان شناسهای باشد که در کل یکپارچگی Fleet Engine شما استفاده میشود و نقشهای حساب سرویس یکسانی داشته باشد. |
| trip_id | بله | رشتهای که ایجاد میکنید و این سفر را بهطور منحصربهفرد شناسایی میکند. شناسههای سفر محدودیتهای خاصی دارند که در مرجع نشان داده شده است. |
| trip_type | بله | TripType را برای نوع سفری که ایجاد میکنید روی مقادیر زیر تنظیم کنید:
|
| pickup_point | بله | نقطه مبدأ سفر. |
| مقصدهای میانی | بله | فقط سفرهای چند مقصدی: فهرست مقصدهای میانی که راننده بین
محل سوار شدن و محل پیاده شدن از آنها بازدید میکند. مانند |
| vehicle_waypoints | بله | فقط سفرهای اشتراکی: این فیلد از درهمبافی نقاطمسیر از چندین سفر پشتیبانی میکند.
این فایل شامل همه ایستگاههای بین راهی باقیمانده برای وسیله نقلیه اختصاصیافته و همچنین
ایستگاههای بین راهی تحویل و تحویلگیری برای این سفر است. میتوانید این فیلد را
با فراخوانی |
| 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 پایان مییابد.
برای سفر چند مقصدی، علاوهبر بهروزرسانی وضعیت سفر همانگونه که برای سفر تکمقصد انجام میدهید، باید هر بار که وسیله نقلیهتان به مقصد میانی میرسد موارد زیر را نیز بهروزرسانی کنید:
intermediateDestinationIndexintermediateDestinationsVersion
برای انجام این کار، از مقادیر زیر از شمارش TripStatus استفاده کنید.
ENROUTE_TO_PICKUPARRIVED_AT_PICKUPENROUTE_TO_INTERMEDIATE_DESTINATIONARRIVED_AT_INTERMEDIATE_DESTINATIONENROUTE_TO_DROPOFFCOMPLETE
نمونه سفر با مقصدهای بینراهی
در زیر نحوه ایجاد سفر چندمقصدی که از نقطه سوار کردن مسافر عبور کرده است و اکنون در مسیر اولین مقصد میانی است نشان داده شده است.
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;
}