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

מסמך זה מניח שקראת את מדריך המבוא כדי משימות מתוזמנות גם בקטע Introduction to 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 בלבד: המספר או המזהה שבהם אתם משתמשים כדי לעקוב אחרי משלוח. לא מומלץ מציינים את השדה הזה למשימות שלא קשורות למשלוח.
plannedLocation PICKUP, DELIVERY, או SCHEDULED_STOP משימות בלבד: המיקום שבו צריך להשלים את המשימה. לא נדרש עבור: UNAVAILABLE משימות.
taskDuration משך הזמן הצפוי כדי להשלים את המשימה. לדוגמה, כדי לחפש חניה או ללכת למיקום המסירה.

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

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

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

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

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

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

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

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

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

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

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

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

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

כותרת הבקשה חייבת להכיל שדה Authorization עם הערך נושא <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
 ```

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