REST Resource: providers.tasks

משאב: משימה

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

הערה: בממשקי ה-API ל-gRPC ול-REST נעשה שימוש במסורות שונות של מתן שמות לשדות. לדוגמה, השדה Task.journey_sharing_info ב-gRPC API והשדה Task.journeySharingInfo ב-REST API מתייחסים לאותו שדה.

ייצוג ב-JSON 
{
  "name": string,
  "type": enum (Type),
  "state": enum (State),
  "taskOutcome": enum (TaskOutcome),
  "taskOutcomeTime": string,
  "taskOutcomeLocation": {
    object (LocationInfo)
  },
  "taskOutcomeLocationSource": enum (TaskOutcomeLocationSource),
  "trackingId": string,
  "deliveryVehicleId": string,
  "plannedLocation": {
    object (LocationInfo)
  },
  "taskDuration": string,
  "targetTimeWindow": {
    object (TimeWindow)
  },
  "journeySharingInfo": {
    object (JourneySharingInfo)
  },
  "taskTrackingViewConfig": {
    object (TaskTrackingViewConfig)
  },
  "attributes": [
    {
      object (TaskAttribute)
    }
  ]
}
שדות
name

string

הפורמט הנדרש הוא providers/{provider}/tasks/{task}.
type

enum (Type)

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

enum (State)

חובה. מצב הביצוע הנוכחי של המשימה.
taskOutcome

enum (TaskOutcome)

התוצאה של המשימה.
taskOutcomeTime

string (Timestamp format)

חותמת הזמן שמציינת מתי הספק הגדיר את התוצאה של Task.

הפורמט הזה משתמש ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמלי לפי Z וישמש בספרות עשרוניות של 0, 3, 6 או 9. אפשר להשתמש גם בשינויים (offsets) אחרים מלבד 'Z'. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
taskOutcomeLocation

object (LocationInfo)

המיקום שבו הוגדרה התוצאה של Task. הערך הזה מתעדכן כחלק מ-tasks.patch. אם הספק לא מעדכן את הערך הזה באופן מפורש, מערכת Fleet Engine מאכלסת אותו כברירת מחדל במיקום האחרון הידוע של הרכב (המיקום הגולמי).
taskOutcomeLocationSource

enum (TaskOutcomeLocationSource)

מציין מאיפה הגיע הערך של taskOutcomeLocation.
trackingId

string

לא ניתן לשינוי. השדה הזה מאפשר לשמור מזהה כדי להימנע משימוש במיפוי מורכב. לא ניתן להגדיר את trackingId למשימות מסוג UNAVAILABLE ו-SCHEDULED_STOP. המזהים האלה כפופים להגבלות הבאות:

  • צריכה להיות מחרוזת Unicode חוקית.
  • האורך המקסימלי הוא 64 תווים.
  • מנורמלים בהתאם לפורמט נירמול C של Unicode.
  • אסור לכלול את תווים ה-ASCII הבאים: '/',‏ ':',‏ '?',‏ ',' או '#'.
deliveryVehicleId

string

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

  • צריכה להיות מחרוזת Unicode חוקית.
  • האורך המקסימלי הוא 64 תווים.
  • מנורמלים בהתאם לפורמט נירמול C של Unicode.
  • אסור לכלול את תווים ה-ASCII הבאים: '/',‏ ':',‏ '?',‏ ',' או '#'.
plannedLocation

object (LocationInfo)

לא ניתן לשינוי. המיקום שבו המשימה תושלם. אופציונלי למשימות UNAVAILABLE, אבל חובה לכל המשימות האחרות.
taskDuration

string (Duration format)

חובה. לא ניתן לשינוי. הזמן הדרוש לביצוע משימה במיקום הזה.

משך הזמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'s'. דוגמה: "3.5s".
targetTimeWindow

object (TimeWindow)

חלון הזמן שבו המשימה צריכה להסתיים.
journeySharingInfo

object (JourneySharingInfo)

פלט בלבד. שדות ספציפיים לשיתוף המסלול. השדה לא מאוכלס כשהסטטוס הוא CLOSED.
taskTrackingViewConfig

object (TaskTrackingViewConfig)

ההגדרה של מעקב המשימות, שמציינת אילו רכיבי נתונים גלויים למשתמשי הקצה ובאילו נסיבות.
attributes[]

object (TaskAttribute)

רשימה של מאפייני משימות מותאמים אישית. לכל מאפיין צריך להיות מפתח ייחודי.

סוג

סוג המשימה.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED כברירת מחדל, סוג המשימה לא ידוע.
PICKUP משימה של איסוף היא הפעולה שמתבצעת כדי לאסוף משלוח מלקוח. כשמקבלים הודעות על איסוף כלי רכב במסוף או על איסוף כלי רכב מרכזיים, צריך להשתמש בסוג SCHEDULED_STOP.
DELIVERY משימה של משלוח היא הפעולה שמתבצעת כדי לספק משלוח ללקוח קצה. כדי לציין הורדות של כלי רכב במסוף או של כלי רכב להעברת נוסעים, צריך להשתמש בסוג SCHEDULED_STOP.
SCHEDULED_STOP משימה של עצירה מתוזמנת משמשת למטרות תכנון. לדוגמה, האירוע יכול לייצג איסוף או מסירה של משלוחים מכלי רכב או ממאגרים. אסור להשתמש בו בשביל משלוחים שנאספים או נמסרים על ידי לקוח קצה.
UNAVAILABLE משימה שמציינת שהרכב לא זמין לשירות. לדוגמה, זה יכול לקרות כשהנהג מפסיק לצורך הפסקה או כשהרכב מתדלק.

TaskOutcomeLocationSource

הזהות של המקור שאכלס את taskOutcomeLocation.

טיפוסים בני מנייה (enum)
TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED תוצאת המשימה לפני שהיא מוגדרת.
PROVIDER הספק ציין את taskOutcomeLocation.
LAST_VEHICLE_LOCATION הספק לא ציין את taskOutcomeLocation, לכן מערכת Fleet Engine השתמשה במיקום האחרון הידוע של הרכב.

JourneySharingInfo

שדות ספציפיים לשיתוף המסלול.

ייצוג ב-JSON 
{
  "remainingVehicleJourneySegments": [
    {
      object (VehicleJourneySegment)
    }
  ],
  "lastLocation": {
    object (DeliveryVehicleLocation)
  },
  "lastLocationSnappable": boolean
}
שדות
remainingVehicleJourneySegments[]

object (VehicleJourneySegment)

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

הקטע הראשון, Task.journey_sharing_info.remaining_vehicle_journey_segments[0] (gRPC) או Task.journeySharingInfo.remainingVehicleJourneySegments[0] (REST), מכיל את פרטי המסלול מהמיקום האחרון הידוע של הנהג/ת אל VehicleStop הקרוב. בדרך כלל, פרטי המסלול הנוכחי מגיעים מאפליקציית הנהג, מלבד במקרים מסוימים שמפורטים במסמכי התיעוד של DeliveryVehicle.current_route_segment. הפלחים האחרים ב-Task.journey_sharing_info.remaining_vehicle_journey_segments‏ (gRPC) או ב-Task.journeySharingInfo.remainingVehicleJourneySegments‏ (REST) מאוכלסים על ידי Fleet Engine. הם מספקים מידע על המסלול בין VehicleStops הנותרים.
lastLocation

object (DeliveryVehicleLocation)

המיקום האחרון שדווח על הרכב שהוקצה.
lastLocationSnappable

boolean

מציין אם ניתן להתאים את lastLocation של הרכב ל-currentRouteSegment. הערך הזה הוא False אם lastLocation או currentRouteSegment לא קיימים. הערך הזה מחושב על ידי Fleet Engine. המערכת מתעלמת מעדכונים מהלקוחות.

TaskTrackingViewConfig

הודעת התצורה שמגדירה מתי רכיב נתונים של משימה צריך להיות גלוי למשתמשי הקצה.

ייצוג ב-JSON 
{
  "routePolylinePointsVisibility": {
    object (VisibilityOption)
  },
  "estimatedArrivalTimeVisibility": {
    object (VisibilityOption)
  },
  "estimatedTaskCompletionTimeVisibility": {
    object (VisibilityOption)
  },
  "remainingDrivingDistanceVisibility": {
    object (VisibilityOption)
  },
  "remainingStopCountVisibility": {
    object (VisibilityOption)
  },
  "vehicleLocationVisibility": {
    object (VisibilityOption)
  }
}
שדות
routePolylinePointsVisibility

object (VisibilityOption)

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

object (VisibilityOption)

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

object (VisibilityOption)

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

object (VisibilityOption)

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

object (VisibilityOption)

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

object (VisibilityOption)

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

VisibilityOption

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

ייצוג ב-JSON 
{

  // Union field visibility_option can be only one of the following:
  "remainingStopCountThreshold": integer,
  "durationUntilEstimatedArrivalTimeThreshold": string,
  "remainingDrivingDistanceMetersThreshold": integer,
  "always": boolean,
  "never": boolean
  // End of list of possible types for union field visibility_option.
}
שדות
שדה האיחוד visibility_option. אפשרות החשיפה הספציפית שנבחרה. הערך של visibility_option יכול להיות רק אחת מהאפשרויות הבאות:
remainingStopCountThreshold

integer

רכיב הנתונים הזה גלוי למשתמשי הקצה אם מספר תחנות העצירה שנותרו <= remainingStopCountThreshold.
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

רכיב הנתונים הזה גלוי למשתמשי הקצה אם זמן ההגעה המשוער לתחנה <= durationUntilEstimatedArrivalTimeThreshold.

משך הזמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'s'. דוגמה: "3.5s".
remainingDrivingDistanceMetersThreshold

integer

רכיב הנתונים הזה גלוי למשתמשי הקצה אם מרחק הנסיעה שנותר במטרים <= remainingDrivingDistanceMetersThreshold.
always

boolean

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

boolean

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

Methods

batchCreate

 יצירת קבוצה של אובייקטים חדשים מסוג Task והחזרתה.

create

 יצירת אובייקט Task חדש והחזרתו.

delete

 מחיקה של משימה אחת.

get

 הפונקציה מקבלת מידע על Task.

list

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

patch

 עדכון הנתונים של Task.