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

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

• הגדרת Fleet Engine
• יצירת רכב
• תרחישי נסיעות בסקירה הכללית של נסיעות על פי דרישה

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

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

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

הערה: כדי להשתמש ב-CreateTrip(), צריך את פרטי הכניסה לחשבון בעל ההרשאות שמוזכר במאמר Fleet Engine: Service account roles.

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

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

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

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

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

הערה: בכל פעם שמגדירים או מעדכנים את intermediate_destinations בנסיעה, המערכת של Fleet Engine מאכלסת את intermediate_destinations_version בישויות הנסיעה שנוצרות. צריך לשמור את השדה הזה במטמון במערכת ולהעביר את הערך של UpdateTripRequest כשמעדכנים את intermediate_destination_index מאוחר יותר. כך היעדים הביניים יסתנכרנו בין לקוח הנהג לבין 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

הערה: הנסיעה צריכה לעבור דרך ENROUTE_TO_INTERMEDIATE_DESTINATION וגם ARRIVED_AT_INTERMEDIATE_DESTINATION פעם אחת לכל יעד ביניים.

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

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

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

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

• יצירת נסיעות ברצף
• הגדרת Driver SDK