עדכון הנסיעות וניהול המצב שלהן

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

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

המערכת משתמשת ב-Fleet Engine כדי לעדכן נסיעה במצבים הבאים:

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

כדי לעדכן נסיעה, שולחים בקשה באמצעות gRPC או REST.

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

משתמשים בפרטי הכניסה המתאימים לחשבון השירות של הפרויקט, כפי שמתואר במאמר Fleet Engine: תפקידים של חשבונות שירות.

עדכון השדות של הנסיעה

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

שימוש במסכות שדות

מסכות שדות הן דרך שמאפשרת למפעילי ה-API לרשום את השדות שצריך לשלוח בבקשה או לעדכן אותה. שימוש ב-FieldMask ימנע עבודה מיותרת וישפר את הביצועים. ‏Fleet Engine משתמש במסכות שדות כדי לעדכן שדות בכל המשאבים.

עדכון הנסיעה עם מזהה הרכב

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

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, 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:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

ניהול מצב הנסיעה

כדי לציין את המצב של נסיעה, צריך להשתמש באחד מערכי המנייה TripStatus. כשהסטטוס של נסיעה משתנה, למשל מ-ENROUTE_TO_PICKUP ל-ARRIVED_AT_PICKUP, מעדכנים את סטטוס הנסיעה ב-Fleet Engine. מחזור החיים של הנסיעה תמיד מתחיל בערך המצב NEW ומסתיים בערך COMPLETE או CANCELED.

דוגמה לעדכון נסיעה

בדוגמה הבאה מוסבר איך לעדכן את סטטוס הנסיעה של נסיעה רצופה ב-Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .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:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

דוגמאות נוספות לעדכון נסיעות מפורטות בקטע סוגי נסיעות אחרים.

טיפול בשגיאות בנסיעות

כשמעדכנים נסיעות קיימות או מחפשים אותן, יכול להיות שתופיע שגיאה מסוג DEADLINE_EXCEEDED. במקרה כזה, המצב של Fleet Engine לא ידוע. כדי לבדוק את זה, קודם צריך להתקשר שוב אל CreateTrip עם אותו מזהה נסיעה שאת/ה מנסה לעדכן או לעקוב אחריו. התגובה אמורה להיות 201 (CREATED) או 409 (CONFLICT). במקרה השני, הבקשה הקודמת הסתיימה בהצלחה לפני DEADLINE_EXCEEDED.

אפשר לעיין ברשימת שגיאות הרשת ב-Consumer SDK ל-Android או ל-iOS.

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