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

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

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

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

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

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

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

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

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

שדהערך
type

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

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

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

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

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

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

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

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> הוא אסימון שהונפקה על ידי השרת בהתאם להנחיות שמפורטות במאמרים תפקידים בחשבון שירות ואסימוני JSON Web.

גוף הבקשה חייב לכלול ישות 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": "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.

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

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> הוא אסימון שהונפקה על ידי השרת בהתאם להנחיות שמפורטות במאמרים תפקידים בחשבון שירות ואסימוני JSON Web.

גוף הבקשה חייב לכלול ישות 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
 ```

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