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

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

ב-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> הוא מזהה ייחודי של המשימה.

כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>‎, כאשר <token>‎ מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים [תפקידים בחשבון שירות][6] ו[אסימוני JSON Web][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.

בדוגמאות הבאות מוצגות שתי דרכים ליצור משימת איסוף משלוח: באמצעות [ספריית 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> הוא מזהה ייחודי של המשימה.

כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>‎, כאשר <token>‎ מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים [תפקידים בחשבון שירות][6] ו[אסימוני JSON Web][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