יצירת משימות משלוח

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

ב-Fleet Engine למשימות מתוזמנות יש קטגוריות רחבות שונות של משימות:

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

במאמר הזה מוסבר איך ליצור משימות משלוח בשרת. לסוגי משימות אחרים, ראו יצירת סוגי משימות אחרים.

שדות של משימות משלוח

בקטע הזה מתוארים שדות המשימה שנדרשים גם למשימות איסוף וגם למשימות מסירה.

שדות חובה במשימות

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

שדהערך
type

צריך להגדיר את הסוג שתואם לסוג המשימה, שהוא אחד מהבאים:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id מזהה משימה ייחודי. המספר הזה לא יכול להיות מספר המעקב של המשלוח. אם אין לכם מזהי משימות במערכת, אתם יכולים ליצור מזהה ייחודי אוניברסלי (UUID). לפרטים נוספים, ראו מזהי משימות.
tracking_id משימות מסוג PICKUP או DELIVERY בלבד: המספר או המזהה שמשמשים למעקב אחרי משלוח. אל תציינו את השדה הזה במשימות שאינן משלוח.
planned_location ‫משימות מסוג PICKUP, DELIVERY או SCHEDULED_STOP בלבד: המיקום שבו צריך להשלים את המשימה. לא נדרש למשימות של UNAVAILABLE.
task_duration הזמן המשוער להשלמת המשימה. לדוגמה, כדי לחפש חנייה או ללכת למיקום של העברת החבילה.

שדות אופציונליים של משימות משלוח

שדהערך
target_time_window חלון הזמן שבו צריך להשלים את המשימה. השדה הזה לא משפיע על אופן הניתוב.
task_tracking_view_config ‫PICKUP או DELIVERY משימות בלבד: ההגדרה של מעקב אחר משימות, שמציינת אילו רכיבי נתונים גלויים למשתמשי הקצה ובאילו נסיבות.
attributes רשימה של מאפייני משימות בהתאמה אישית. לכל מאפיין צריך להיות מפתח ייחודי.

יצירת משימה לאיסוף משלוח

כדי להשתמש ב-Fleet Engine כדי לעקוב אחרי הפעילות של נהג שאוסף משלוח, צריך ליצור משימה של איסוף משלוח. כדי לעשות את זה, צריך להגדיר את מאפיין סוג המשימה כ-PICKUP. הדוגמה הבאה ממחישה איסוף משלוח מ-Grand Indonesia East Mall.

בדוגמאות הבאות מוסבר איך ליצור משימת איסוף משלוח באמצעות [ספריית Java gRPC][4] או איך לשלוח בקשת HTTP REST אל [CreateTask][5].

gRPC

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

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.PICKUP)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have a task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

כדי ליצור משימה לאיסוף משלוח מסביבת שרת, שולחים קריאת HTTP REST אל CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

‫<id> הוא מזהה ייחודי של המשימה.

ה-request header חייב להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות בקטעים [תפקידים של חשבונות שירות][6] ו-[אסימוני אינטרנט מסוג JSON‏][7].

גוף הבקשה חייב להכיל ישות Task עם השדות המתאימים שמתוארים בקטע [שדות של משימות משלוח][8].

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

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "PICKUP",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM

יצירת משימת מסירה של משלוח

כדי להשתמש ב-Fleet Engine כדי לעקוב אחרי הפעילות של נהג שמוסר משלוח, צריך ליצור משימת מסירת משלוח. כדי לעשות את זה, צריך להגדיר את מאפיין סוג המשימה כ-DELIVERY. הדוגמה הבאה ממחישה משלוח לקניון Grand Indonesia East Mall.

בדוגמאות הבאות מוסבר איך ליצור משימת איסוף משלוח באמצעות [ספריית Java gRPC][4] או איך לשלוח בקשת HTTP REST אל [CreateTask][5].

gRPC

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

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.DELIVERY)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

כדי ליצור משימה לאיסוף משלוח מסביבת שרת, שולחים קריאת HTTP REST אל CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

‫<id> הוא מזהה ייחודי של המשימה.

ה-request header חייב להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות בקטעים [תפקידים של חשבונות שירות][6] ו-[אסימוני אינטרנט מסוג JSON‏][7].

גוף הבקשה חייב להכיל ישות Task:

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

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "DELIVERY",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 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

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

  • [יצירת סוגים אחרים של משימות][13]
  • [עדכון משימות][3]

[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks