הגדרת משימות

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

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

  • התאמה אישית של הרשאות הגישה למשימות: אפשר להתאים אישית את הרשאות הגישה לפעילויות של המשימות כדי להציג אותן ללקוחות או למפעילי צי הרכב.

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

הגדרת חלון הזמן לטירגוט

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

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

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

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String TASK_ID = "task-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
  Task task = Task.newBuilder()
    .setName(taskName)
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .build();

  // Task request
  UpdateTaskRequest updateTaskRequest =
    UpdateTaskRequest.newBuilder()  // No need for the header
        .setTask(task)
        .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
        .build();

  try {
    Task updatedTask = deliveryService.updateTask(updateTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

כדי להגדיר חלון זמן של משימה באמצעות HTTP, צריך להפעיל את PATCH ולהשתמש ב-updateMask כדי לעדכן את הפרמטר targetTimeWindow:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow

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

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "targetTimeWindow": {
      "startTime": "2023-03-29T21:00:00Z",
      "endTime": "2023-03-29T23:00:00Z"
    }
  }
  EOM

התאמה אישית של הרשאות הגישה למשימות

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

בקטע הזה מתוארים כללי החשיפה של אובייקטים במפה שאחריהם אתם עוקבים. הכללים האלה חלים על שתי קטגוריות של אובייקטים:

  • החשיפה של סמן המיקום
  • הרשאת גישה לנתוני המשימות של כלי רכב פעילים, כמו קווים פוליגוניים וזמן הגעה משוער

כללי חשיפה של סמני מיקום

מערכת Fleet Engine מציגה סמנים של מיקומים של משלוח, שמופיעים במפה, ללא קשר למצב המשלוח.

כללי הגדרת הרשאות גישה לנתוני המשימות

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

לא ניתן להתאים אישית את המשימות הבאות:

  • עצירות מתוזמנות
  • משימות של זמינות מוגבלת
  • משימות לא פעילות של כלי רכב

כללי הרשאות גישה למשימות של זמינות מוגבלת

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

החשיפה של משימות פעילות של כלי רכב

האובייקט TaskTrackingInfo מספק מספר רכיבי נתונים שאפשר להציג באמצעות Shipment Tracking Library. כברירת מחדל, השדות האלה גלויים כשהמשימה מוקצית לרכב וכשהרכב נמצא בטווח של 5 תחנות מהמשימה. החשיפה תסתיים כשהמשימה תושלם או תבוטל.

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

בטבלה הבאה מפורטים השדות שאפשר להחיל עליהם כללי חשיפה.

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

בטבלה הזו מוצגות אפשרויות החשיפה הזמינות לשדות שמפורטים למעלה.

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

קווים פוליגונים של מסלולים וכללי חשיפה של מיקום הרכב

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

פועלים לפי הכללים הבאים כדי לספק שילוב תקין של קווים פוליגונליים של מסלול או של חשיפה של מיקום הרכב.

לקו הפוליגון של המסלול ולמיקום הרכב יש אותן אפשרויות חשיפה

בתרחיש הזה, גם לקו הפוליגון וגם למיקום הרכב מוגדרות אותן אפשרויות, כולל:

  • מספר תחנות העצירה שנותרו
  • משך הזמן עד לזמן ההגעה המשוער
  • מרחק הנסיעה שנותר

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

```js
"taskTrackingViewConfig": {
  "routePolylinePointsVisibility": {
    "remainingStopCountThreshold": 3
  },
  "vehicleLocationVisibility": {
    "remainingStopCountThreshold": 5
  },
}
```

קווים פוליגונים של מסלולים ומיקום הרכב מציינים את האפשרויות השונות של החשיפה

כשיש לקו הפוליגון של המסלול ולמיקום הרכב אפשרויות שונות של חשיפה, מיקום הרכב גלוי רק כששתיהן מתקיימות. שוב, החשיפה של קו הפוליגון כפופה לכללי החשיפה של הרכב:

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

דוגמה:

  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "vehicleLocationVisibility": {
      "remainingDrivingDistanceMetersThreshold": 3000
    },
  }

בדוגמה הזו, מיקום הרכב גלוי רק אם מספר העצירות שנותרו הוא לפחות 3 וגם אם מרחק הנסיעה שנותר הוא לפחות 3,000 מטרים.

דוגמה להתאמה אישית של הרשאות הגישה למשימות

בדוגמאות הבאות מוסבר איך להגדיר משימה עם כללי הגלוי הבאים:

  • הצגת קווים פוליגונים של המסלול אם הרכב נמצא בטווח של 3 תחנות.
  • הצגת זמן ההגעה המשוער אם המרחק שנותר לנסיעה קצר מ-5,000 מטרים.
  • אני לא רוצה לראות את מספר התחנות שנותרו.
  • כל שדה אחר יישאר גלוי כברירת מחדל, והוא יוצג כשהרכב יהיה במרחק של 5 תחנות מהמשימה.

TaskTrackingViewConfig ל-gRPC או ל-REST.

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

כדי להגדיר את חלון ההגדרה של תצוגת מעקב המשימות באמצעות HTTP, צריך להפעיל את PATCH ולהשתמש ב-updateMask כדי לעדכן את הפרמטר taskTrackingViewConfig:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig

לדוגמה:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

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