יצירת נסיעות מאגר משותפות

במסמך הזה מתואר איך ליצור נסיעה משותפת, להגדיר את שדות, ולהקצות אותו לרכב למילוי. ההנחה היא שהגדרתם את Fleet Engine, יצרתם כלי רכב, יש לכם אפליקציה שפועלת לנהגים ואפליקציה שפועלת לצרכנים (אופציונלי). בנוסף, אתם צריכים להכיר את התרחישים השונים של נסיעות שזמינות בנסיעות על פי דרישה. אפשר לעיין במדריכים הקשורים הבאים לגבי ש:

יסודות של יצירת נסיעות

בקטע הזה מתוארים פרטי הבקשה הנדרשים ליצירת נסיעה ב-Fleet Engine. שולחים בקשת יצירה באמצעות gRPC ו-REST.

  • שיטת CreateTrip(): gRPC או REST
  • הודעה אחת (CreateTripRequest): ב-gRPC בלבד

שדות נסיעה

צריך להשתמש בשדות הבאים כדי ליצור נסיעה ב-Fleet Engine. אפשר להשתמש בשדות שונים לסוגים השונים של נסיעות: נסיעות ליעד יחיד או למספר יעדים, נסיעות ברצף או נסיעות משותפות בקבוצה. אפשר למלא את השדות האופציונליים כשיוצרים את הנסיעה, או להגדיר אותם מאוחר יותר כשמעדכנים את הנסיעה.

שדות נסיעה
שם נדרש? תיאור
הורה כן מחרוזת שכוללת את מזהה הפרויקט. המזהה הזה חייב להיות אותו המזהה שבו אתם משתמשים בכל השילוב של Fleet Engine, עם אותו חשבון שירות תפקידים.
trip_id כן מחרוזת שיוצרים שמזהה באופן ייחודי את הנסיעה הזו. יש למזהי נסיעות הגבלות מסוימות, כפי שמצוין בחומר העזר.
trip_type כן מגדירים את TripType לערכי הנסיעה הבאים:
  • יעד יחיד: צריך להגדיר את הערך SHARED או EXCLUSIVE.
  • Multi-destination: מגדירים את הערך EXCLUSIVE.
  • חזרה אחורה: מוגדר ל-EXCLUSIVE.
  • Shared pooling: מגדירים את הערך 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) בנסיעה. ציים המנוע משתמש ברשימה הזו כדי לעדכן באופן אוטומטי את נקודות העצירה בנסיעה בכל הנסיעות במאגר המשותף.

לדוגמה, נניח שיש שתי נסיעות במאגר משותף, נסיעה א' ו-נסיעה ב':

  • נסיעה א' נמצאת בדרך לנקודת המוצא שלה.
  • לאחר מכן, נסיעה ב מתווספת לאותו רכב.

ב-UpdateTripRequest אחד של נסיעה ב', מגדירים את vehicleId, וגם מגדירים את Trip.vehicle_waypoints בסדר הנקודות האופטימלי: B Pickup‏ → A Drop-off‏ → B Drop-off.

  • קריאה ל-getVehicle() מחזירה את remainingWaypoints שמכיל:
    B PickupA Drop-offB Drop-off.
  • getTrip() או הקריאה החוזרת onTripRemainingWaypointsUpdated עבור נסיעה א' מחזירה את remainingWaypoints שמכיל:
    B PickupA Drop-off.
  • getTrip() או הקריאה החוזרת onTripRemainingWaypointsUpdated עבור נסיעה B מחזירה את remainingWaypoints שמכיל את הפרטים הבאים:
    B PickupA Drop-offB Drop-off.

דוגמה

דוגמת השילוב הבאה של הקצה העורפי מדגימה איך לעדכן נסיעה עם מזהה הרכב וציוני הדרך לשתי נסיעות במאגר משותף.

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

המאמרים הבאים