עדכון שדות הרכב

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

  • vehicle_state: קובע את הזמינות של הרכב לנסיעות חדשות.
  • vehicle_type: שדה חובה כשיוצרים רכב. השדה יכול לשמש גם כקריטריון סינון להתאמות של כלי רכב. פרטים על הגדרת השדה הזה מופיעים במאמר יצירת רכב.
  • attributes[]: מערך אופציונלי מסוג VehicleAttribute. אפשר להשתמש בהם כדי להגדיר קריטריונים מותאמים אישית לשיפור התנהגות הסינון כשמחפשים רכבים או כשמציגים אותם באתר.
  

רשימה מלאה של השדות של כלי רכב מופיעה במאמרים הבאים:

שדה מצב הרכב

המערכת יכולה להגדיר את מצב הרכב כ-OFFLINE או כ-ONLINE. לדוגמה, אפשר להגדיר את מצב הרכב ל-ONLINE כל יום בשעה 9:00 ול-OFFLINE כל יום בשעה 17:00.

מצב אופליין מצב ONLINE
משתמשים ב-OFFLINE כדי לציין שכלי רכב לא מקבל נסיעות חדשות. חשוב לזכור שהרכב עדיין יכול להשלים נסיעות שהוקצו לו במצב הזה.
  • Vehicle שנוצר במצב ONLINE עשוי להוחזר באופן מיידי בתגובה לשאילתות SearchVehicles. פרטים נוספים זמינים במאמר חיפוש רכבים.
  • ברכבים שנוצרו במצב ONLINE צריך להשתמש בשדה last_location בקריאה CreateVehicle.

השדה 'מאפייני הרכב'

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

לדוגמה, אפשר להצהיר על מאפיין מותאם אישית בשם class כדי להבדיל בין כלי הרכב של שירותי הנסיעה המשותפת לפי רמות הכיתה. כדי לייצג את רמות סיווג הרכב, משתמשים בערכים הבאים של מחרוזות: ECONOMY, ‏ STANDARD ו-LUXURY.

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

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

עדכון מאפייני הרכב

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

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

דוגמה לעדכון שדות של כלי רכב

בקטע הזה מוסבר איך לעדכן את השדות של הרכב באמצעות UpdateVehicleRequest, שכוללת את השדה update_mask כדי לציין אילו שדות לעדכן. לפרטים נוספים, אפשר לעיין במסמכי התיעוד של Protocol Buffers בנושא מסכות שדות.

כדי לעדכן שדות שאינם last_location, נדרשות הרשאות אדמין על פי דרישה של Fleet Engine.

דוגמה: הפעלת סוג נסיעה חדש ומאפיין מותאם אישית

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

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

למידע נוסף, ראו את המסמך providers.vehicles.update לגבי gRPC ו-REST.

gRPC

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("class").setValue("ECONOMY").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

REST

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "class", "value": "LUXURY"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

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