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.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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 Normalization Form 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)

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

סוג

סוג המשימה.

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

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

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

integer

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

boolean

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

boolean

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

שיטות

batchCreate

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

create

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

get

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

list

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

patch

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