עדכון של סטטוס העצירה

המסמך הזה מיועד למי שמכיר את הנושאים הבאים:

  • [יצירת משימות משלוח][1]
  • ההקדמה ל[משימות מתוזמנות][3], שכוללת הסבר מפורט על הקשר בין משימות, עצירות וכלי רכב.

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

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

  • ‫En route: הערך STATE enum של VehicleStop משתמש ב-ENROUTE כדי לציין שהתחנה היא הבאה ברשימה של מסלול הנסיעה של הרכב. מנקודת המבט של המשימה, המשמעות היא שכל משימה שמשויכת לעצירה היא הבאה ברשימה שצריך להשלים.
  • הגיע: הערך STATE enum של VehicleStop הוא ARRIVED, שמציין שהרכב הגיע לתחנה. מנקודת המבט של המשימה, המשמעות היא שכל משימה שמשויכת להפסקה נמצאת בעבודה פעילה.
  • הושלמה: אתם מסמנים עצירה כהושלמה על ידי הסרתה מרשימת העצירות של הרכב. כשעושים את זה, Fleet Engine מסמן באופן אוטומטי את כל המשימות המשויכות כסגורות. פרטים נוספים על סגירת משימות זמינים במאמר בנושא [סגירת משימות][4].

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

הרכב בדרך לתחנה

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

שדות חובה לעדכוני עצירות

‫Fleet Engine מתעלם מכל שאר השדות בישות של ההתראה.

שדהערך
remainingVehicleJourneySegments רשימה של עצירות הרכב שנותרו, עם הסטטוסים שלהן שמסומנים כ-State.NEW.

דוגמה למצב 'בדרך לעצירה'

בדוגמאות הבאות מוצגות דרכים לשלוח ל-Fleet Engine הודעה על כך שהרכב נמצא בדרך לתחנה הבאה שלו, באמצעות [ספריית Java gRPC][5] או קריאת HTTP REST אל UpdateDeliveryVehicle.כל התחנות האחרות מסומנות כחדשות.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String VEHICLE_ID = "vehicle-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Vehicle settings
 DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
     // Next stop marked as ENROUTE
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.7749)
                    .setLongitude(122.4194)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
            .setState(VehicleStop.State.ENROUTE)))
     // All other stops marked as NEW
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.3382)
                    .setLongitude(121.8863)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
            .setState(VehicleStop.State.NEW)))
     .build();

 // DeliveryVehicle request
 UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
   UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
       .setName(vehicleName)
       .setDeliveryVehicle(deliveryVehicle)
       .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
       .build();

 try {
   DeliveryVehicle updatedDeliveryVehicle =
       deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
  • ‫<id> הוא מזהה ייחודי של המשימה.
  • כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים [תפקידים בחשבון שירות][6] ו[אסימוני אינטרנט JSON][6].
  • גוף הבקשה חייב להכיל ישות DeliveryVehicle:

פקודה curl לדוגמה:

 # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
 # environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "remainingVehicleJourneySegments": [
     {
       "stop": {
         "state": "ENROUTE",
         "plannedLocation": {
           "point": {
             "latitude": 37.7749,
             "longitude": -122.084061
           }
         },
         "tasks": [
           {
             "taskId": "${TASK1_ID}"
           }
         ]
       }
     },
     {
       "stop": {
         "state": "NEW",
         "plannedLocation": {
           "point": {
             "latitude": 37.3382,
             "longitude": 121.8863
           }
         },
         "tasks": [
           {
             "taskId": "${TASK2_ID}"
           }
         ]
       }
     }
   ]
 }
 EOM

‫placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo ‫placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html ‫placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place ‫placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

רכב מגיע לתחנה

צריך לשלוח ל-Fleet Engine הודעה כשכלי רכב מגיע לתחנה.

שדות חובה לעדכוני עצירות

‫Fleet Engine מתעלם מכל שאר השדות בישות של ההתראה.

שדהערך
remainingVehicleJourneySegments רשימה של עצירות הרכב שנותרו, עם הסטטוסים שלהן שמסומנים כ-State.NEW.

דוגמה להגעה לתחנה

בדוגמאות הבאות מוצגות דרכים לשלוח ל-Fleet Engine הודעה על כך שכלי רכב הגיע לתחנה, באמצעות [ספריית Java gRPC][5] או קריאת HTTP REST אל UpdateDeliveryVehicle. כל התחנות האחרות מסומנות כחדשות.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String VEHICLE_ID = "vehicle-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // Marking the arrival at stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
         .setStop(VehicleStop.newBuilder()
             .setPlannedLocation(LocationInfo.newBuilder()
                 .setPoint(LatLng.newBuilder()
                     .setLatitude(37.7749)
                     .setLongitude(122.4194)))
             .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
             .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as NEW.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
         .setStop(VehicleStop.newBuilder()
             .setPlannedLocation(LocationInfo.newBuilder()
                 .setPoint(LatLng.newBuilder()
                     .setLatitude(37.3382)
                     .setLongitude(121.8863)))
             .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
             .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
      .build();

  // DeliveryVehicle request
  UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
    UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
        .setName(vehicleName)
        .setDeliveryVehicle(deliveryVehicle)
        .setUpdateMask(FieldMask.newBuilder()
            .addPaths("remaining_vehicle_journey_segments"))
        .build();

  try {
    DeliveryVehicle updatedDeliveryVehicle =
        deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
  • ‫<id> הוא מזהה ייחודי של המשימה.
  • כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים [תפקידים בחשבון שירות][6] ו[אסימוני אינטרנט JSON][6].
  • גוף הבקשה חייב להכיל ישות DeliveryVehicle:

פקודה curl לדוגמה:

  # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
  # environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "remainingVehicleJourneySegments": [
      {
        "stop": {
          "state": "ARRIVED",
          "plannedLocation": {
            "point": {
              "latitude": 37.7749,
              "longitude": -122.084061
            }
          },
          "tasks": [
            {
              "taskId": "${TASK1_ID}"
            }
          ]
        }
      },
      {
        "stop": {
          "state": "NEW",
          "plannedLocation": {
            "point": {
              "latitude": 37.3382,
              "longitude": 121.8863
            }
          },
          "tasks": [
            {
              "taskId": "${TASK2_ID}"
            }
          ]
        }
      }
    ]
  }
  EOM

הרכב משלים עצירה

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

שדות חובה לעדכוני עצירות

‫Fleet Engine מתעלם מכל שאר השדות בישות של ההתראה.

שדהערך
remainingVehicleJourneySegments רשימה של עצירות הרכב שנותרו, עם הסטטוסים שלהן שמסומנים כ-State.NEW. התחנה הראשונה ברשימה חייבת להיות מסומנת במצב State.ENROUTE.

מסיים דוגמה לעצירה

בדוגמאות הבאות מוצגות דרכים לשלוח ל-Fleet Engine הודעה על כך שכלי רכב הגיע לתחנה, באמצעות [ספריית Java gRPC][5] או קריאת HTTP REST אל UpdateDeliveryVehicle. כל התחנות האחרות מסומנות כחדשות.

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String VEHICLE_ID = "vehicle-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // This stop has been completed and is commented out to indicate it
      // should be removed from the list of vehicle journey segments.
      // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
      //    .setStop(VehicleStop.newBuilder()
      //        .setPlannedLocation(LocationInfo.newBuilder()
      //            .setPoint(LatLng.newBuilder()
      //                .setLatitude(37.7749)
      //                .setLongitude(122.4194)))
      //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
      //        .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as NEW.
      // The next stop could be marked as ENROUTE if the vehicle has begun
      // its journey to the next stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
         .setStop(VehicleStop.newBuilder()
             .setPlannedLocation(LocationInfo.newBuilder()
                 .setPoint(LatLng.newBuilder()
                     .setLatitude(37.3382)
                     .setLongitude(121.8863)))
             .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
             .setState(VehicleStop.State.NEW)))
      .build();

  // DeliveryVehicle request
  UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
    UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
        .setName(vehicleName)
        .setDeliveryVehicle(deliveryVehicle)
        .setUpdateMask(FieldMask.newBuilder()
            .addPaths("remaining_vehicle_journey_segments"))
        .build();

  try {
    DeliveryVehicle updatedDeliveryVehicle =
        deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
  • ‫<id> הוא מזהה ייחודי של המשימה.
  • כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים [תפקידים בחשבון שירות][6] ו[אסימוני אינטרנט JSON][6].
  • גוף הבקשה חייב להכיל ישות DeliveryVehicle:

פקודה curl לדוגמה:

 # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
 # environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "remainingVehicleJourneySegments": [
     {
       "stop": {
         "state": "NEW",
         "plannedLocation": {
           "point": {
             "latitude": 37.3382,
             "longitude": 121.8863
           }
         },
         "tasks": [
           {
             "taskId": "${TASK2_ID}"
           }
         ]
       }
     }
   ]
 }
 EOM

‫placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo ‫placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html ‫placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place ‫placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

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

  • [השלמת משימות][4]

‫[1]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks ‫[3]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro ‫[4]: /maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks ‫[5]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks ‫[6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts