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

במסמך הזה אנחנו מניחים שקראתם את מדריך המבוא בנושא משימות מתוזמנות בקטע מבוא ל-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 או באמצעות שליחת בקשת 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 tokens.

גוף הבקשה צריך להכיל ישות 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.

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

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

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