REST Resource: providers.tasks

משאב: משימה

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

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

ייצוג 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.

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
taskOutcomeLocation

object (LocationInfo)

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

enum (TaskOutcomeLocationSource)

מציין את מקור הערך של taskOutcomeLocation.
trackingId

string

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

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

string

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

  • חייבת להיות מחרוזת Unicode חוקית.
  • מוגבל לאורך מקסימלי של 64 תווים.
  • מנורמל לפי טופס נירמול Unicode C.
  • אינו יכול להכיל אף אחד מתווי ה-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)

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

סוג

סוג המשימה.

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

TaskOutcomeLocationSource

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

טיפוסים בני מנייה (enums)
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

התנאי מציין אם אפשר להצמיד את המיקום האחרון של הרכב אל 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

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

string (Duration format)

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

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

integer

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

boolean

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

boolean

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

שיטות

batchCreate

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

create

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

get

 קבלת מידע על Task.

list

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

patch

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

search
(deprecated)

 הוצא משימוש: יש להשתמש במקום זאת ב-GetTaskTrackingInfo.