הגדרת משימות

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

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

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

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

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

חלון הזמן של היעד הוא 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> הוא מזהה ייחודי של המשימה. ה-request header חייב להכיל את השדה Authorization עם הערך Bearer <token>, כאשר <token> מונפק על ידי השרת שלכם בהתאם להנחיות שמתוארות בקטעים תפקידים של חשבונות שירות ואסימוני אינטרנט מסוג JSON.

# 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

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