הגדרת משימות

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

  • הגדרת חלון הזמנים ליעד של משימת משלוח: הגדרת חלון הזמנים להשלמת המשימה.

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

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

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

חלון הזמן של היעד הוא 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> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות במאמרים תפקידים בחשבון שירות ואסימוני JWT‏ (JSON Web Token).

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

מידע נוסף על gRPC או REST זמין במאמר TaskTrackingViewConfig.

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

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