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

מסמך זה מניח שקראת את מדריך המבוא כדי משימות מתוזמנות גם בקטע Introduction to 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
 ```

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