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

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

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

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

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

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

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

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

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

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

// 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 לסדר האופטימלי של נקודות הציון: איסוף ב' ← הורדה א' ← הורדה ב'.

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

דוגמה

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

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

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