REST Resource: providers.tasks

資源：Task

Delivery API 中的 Task 代表要追蹤的單一動作。一般來說，出貨相關工作和休息時間工作有所不同。一個運送作業可以與多個工作相關聯。舉例來說，您可以為上車地點建立一個 Task，下車地點或轉乘地點則建立另一個 Task。此外，特定運送任務可由不同的車輛處理。舉例來說，一輛車輛可以負責取貨，將貨物送往集散地，而另一輛車輛則將同樣貨物從集散地送往送貨地點。

注意：gRPC 和 REST API 使用不同的欄位命名慣例。舉例來說，gRPC API 中的 Task.journey_sharing_info 欄位和 REST API 中的 Task.journeySharingInfo 欄位會參照同一個欄位。

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)

必要欄位。不可變動。定義 Task 的類型。例如休息或出貨。
state

enum (State)

必要欄位。工作目前的執行狀態。
taskOutcome

enum (TaskOutcome)

工作結果。
taskOutcomeTime

string (Timestamp format)

指出供應商設定 Task 結果的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 規格化，並使用 0、3、6 或 9 小數位數。系統也接受「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

不可變動。這個欄位可協助您儲存 ID，避免使用複雜的對應。您無法為類型為 UNAVAILABLE 和 SCHEDULED_STOP 的工作設定 trackingId。這些 ID 適用下列限制：

  • 必須是有效的 Unicode 字串。
  • 長度上限為 64 個半形字元。
  • 根據 Unicode Normalization Form C 進行正規化。
  • 不得包含下列任何 ASCII 字元：'/'、':'、'?'、',' 或 '#'。
deliveryVehicleId

string

僅供輸出。執行此工作任務的車輛 ID。提交運送車輛 ID 時，請注意下列限制：

  • 必須是有效的 Unicode 字串。
  • 長度上限為 64 個半形字元。
  • 根據 Unicode Normalization Form C 規範。
  • 不得包含下列任何 ASCII 字元：'/'、':'、'?'、',' 或 '#'。
plannedLocation

object (LocationInfo)

不可變動。工作完成的地點。UNAVAILABLE 工作可選填，但所有其他工作皆為必填。
taskDuration

string (Duration format)

必要欄位。不可變動。在這個位置執行工作所需的時間。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
targetTimeWindow

object (TimeWindow)

應完成工作時段。
journeySharingInfo

object (JourneySharingInfo)

僅供輸出。旅程分享專用欄位。狀態為 CLOSED 時不會填入。
taskTrackingViewConfig

object (TaskTrackingViewConfig)

工作追蹤的設定，可指定在何種情況下向使用者顯示哪些資料元素。
attributes[]

object (TaskAttribute)

自訂工作屬性清單。每個屬性都必須有專屬鍵。

類型

工作類型。

列舉
TYPE_UNSPECIFIED 預設的 Task 類型為不明。
PICKUP 提貨工作是指從客戶處提貨的動作。車庫或接駁車的接送地點應使用 SCHEDULED_STOP 類型。
DELIVERY 運送工作是指將貨物送交給最終消費者的動作。車庫或接駁車的下車地點應使用 SCHEDULED_STOP 類型。
SCHEDULED_STOP 排程停靠站任務可用於規劃。舉例來說，這可能代表從輔助車輛或車站中接送或卸下貨物。請勿將這項功能用於任何由消費者取件或寄件給消費者的貨件。
UNAVAILABLE 任務，表示車輛無法提供服務。例如，當駕駛人休息或車輛加油時，就可能發生這種情況。

TaskOutcomeLocationSource

填入 taskOutcomeLocation 的來源識別資訊。

列舉
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。如果 lastLocation 或 currentRouteSegment 不存在，則這個值為 False。這個值是由 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)

如果到站預估時間 <= 到達時間前所需時間上限，使用者就會看到這個資料元素。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
remainingDrivingDistanceMetersThreshold

integer

如果剩餘行駛距離 (以公尺為單位) 小於 remainingDrivingDistanceMetersThreshold，使用者就會看到這個資料元素。
always

boolean

如果設為 true，則系統一律會向使用者顯示這個資料元素，且沒有設定門檻。這個欄位無法設為 false。
never

boolean

如果設為 true，系統就會一律向使用者隱藏這個資料元素，且不設門檻。這個欄位無法設為 false。

方法

batchCreate

 建立並傳回一批新的 Task 物件。

create

 建立並傳回新的 Task 物件。

delete

 刪除單一工作。

get

 取得 Task 的相關資訊。

list

 取得符合指定篩選條件的所有 Task。

patch

 更新 Task 資料。