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

במאמר הזה מוסבר איך ליצור נסיעה עם כמה יעדים, להגדיר את השדות הנכונים ולהקצות אותה לרכב לביצוע. ההנחה היא שהגדרתם את 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 לא המזהה של הרכב שהוקצה לנסיעה.

דוגמה: יצירת נסיעה עם כמה יעדים

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

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.

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

  • intermediateDestinationIndex
  • intermediateDestinationsVersion

כדי לעשות את זה, משתמשים בערכים הבאים מהספירה TripStatus.

  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

דוגמה לנסיעה עם יעדי ביניים

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

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

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