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

במסמך הזה יוצאים מנקודת הנחה שקראתם את מדריך המבוא למשימות מתוזמנות בקטע Introduction to Fleet Engine, וגם את What is a scheduled Task? בקטע הזה.

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

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

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

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

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

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

בכל משימה שיוצרים ב-Fleet Engine, צריך לספק את השדות הנדרשים, ואפשר גם לספק את כל השדות האופציונליים. ‏Fleet Engine מתעלם מכל השדות האחרים, ומציג חריגה אם בקשת יצירת המשימה כוללת 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. הדוגמה הבאה ממחישה איסוף משלוח מ-GrandIndonesia 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

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

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

&lt;id&gt; הוא מזהה ייחודי של המשימה.

כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>, שבו השרת <token> מונפק על ידי השרת בהתאם להנחיות שמפורטות בתפקידי חשבון שירות ובאסימוני אינטרנט JSON.

גוף הבקשה חייב לכלול ישות 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. הדוגמה הבאה ממחישה איך לשלוח משלוח לגרנד אינדונזיה מזרח.

בדוגמאות הבאות מוסבר איך ליצור משימה של איסוף משלוח באמצעות ספריית 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

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

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

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

כותרת הבקשה צריכה להכיל את השדה Authorization עם הערך Bearer <token>, שבו השרת <token> מונפק על ידי השרת בהתאם להנחיות שמפורטות בתפקידי חשבון שירות ובאסימוני אינטרנט JSON.

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

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