הגדרת משימות

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

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

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

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

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

חלון הזמן של היעד הוא 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 תחנות מהמשימה.

מידע נוסף זמין במאמרי העזרה של 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

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