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

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

מידע בסיסי על יצירת נסיעות

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

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

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

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

שדות של נסיעות
שם נדרש? תיאור
parent כן מחרוזת שכוללת את מזהה הפרויקט. המזהה הזה צריך להיות זהה למזהה שבו השתמשתם בכל השילוב שלכם עם Fleet Engine, עם אותן הרשאות של חשבון השירות.
trip_id כן מחרוזת שאתם יוצרים ומזהה באופן ייחודי את הנסיעה הזו. יש הגבלות מסוימות על מזהי נסיעות, כפי שמצוין בהפניה.
trip_type כן מגדירים את הערכים הבאים של TripType לסוג הנסיעה שאתם יוצרים:
  • יעד יחיד: מגדירים את הערך SHARED או EXCLUSIVE.
  • מספר יעדים: הערך הוא EXCLUSIVE.
  • Back-to-back: מגדירים לערך EXCLUSIVE.
  • מאגר משותף: הערך שמוגדר הוא SHARED.
pickup_point כן נקודת המוצא של הנסיעה.
יעדים ביניים כן

לנסיעות עם כמה יעדים בלבד: רשימת יעדי הביניים שהנהג מבקר בהם בין נקודת האיסוף לנקודת ההורדה. כמו במקרה של dropoff_point, אפשר להגדיר את השדה הזה גם בשלב מאוחר יותר באמצעות קריאה ל-UpdateTrip, אבל נסיעה עם כמה יעדים מכילה בהגדרה יעדי ביניים.

vehicle_waypoints כן

נסיעות בשירות הסעות שיתופי בלבד: השדה הזה תומך בשילוב של נקודות ציון מכמה נסיעות. הוא מכיל את כל נקודות העצירה שנותרו לרכב שהוקצה, וגם את נקודות העצירה לאיסוף ולמסירה של הנסיעה הזו. אפשר להגדיר את השדה הזה באמצעות קריאה ל-CreateTrip או ל-UpdateTrip. אפשר גם לעדכן את נקודות הציון של הרכב באמצעות השדה waypoints על ידי הפעלת השיטה UpdateVehicle. השירות לא מחזיר את המידע הזה בGetTrip שיחות מטעמי פרטיות.

number_of_passengers לא מספר הנוסעים בנסיעה.
dropoff_point לא היעד של הנסיעה.
vehicle_id לא המזהה של הרכב שהוקצה לנסיעה.

דוגמה: יצירת נסיעה משותפת

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

// 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 משתמש ברשימה הזו כדי לעדכן באופן אוטומטי את נקודות הדרך של כל הנסיעות במאגר המשותף.

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

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

ב-UpdateTripRequest עבור נסיעה ב', מגדירים את vehicleId, וגם מגדירים את Trip.vehicle_waypoints לסדר האופטימלי של נקודות הדרך: B איסוףA הורדהB הורדה.

  • הקריאה getVehicle() מחזירה remainingWaypoints שכוללת:
    B איסוףA הורדהB הורדה.
  • הפונקציה getTrip() או הקריאה החוזרת (callback) onTripRemainingWaypointsUpdated עבור Trip A מחזירה remainingWaypoints שכוללת:
    B PickupA Drop-off.
  • הפונקציה getTrip() או הקריאה החוזרת onTripRemainingWaypointsUpdated של Trip B מחזירה את הערך remainingWaypoints שמכיל את הערכים הבאים:
    B PickupA Drop-offB Drop-off.

דוגמה

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

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

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