REST Resource: providers.tasks

資源：Task

Delivery API 中的一項工作代表要追蹤的單一動作。一般來說，與出貨相關的 Tasks 和中斷工作有區別。一項出貨商品可以有多個相關聯的 Tasks。例如分別設定上車地點和下車或轉乘服務。此外，一批出貨的不同 Tasks 也可以由不同車輛處理。舉例來說，其中一輛車可以處理上車事宜，將運送到中樞系統，另一輛車則負責將相同的貨物從中樞行駛到下車地點。

注意：gRPC 和 REST API 採用不同的欄位命名慣例。舉例來說，gRPC API 中的 Task.journey_sharing_info 欄位與 REST API 中的 DeliveryVehicle.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)

必要欄位。無法變更。定義任務的類型。例如休息或出貨。
state

enum (State)

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

enum (TaskOutcome)

工作的結果。
taskOutcomeTime

string (Timestamp format)

指出供應器設定 Task 結果時間的時間戳記，

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："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

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

  • 必須是有效的萬國碼 (Unicode) 字串。
  • 長度上限為 64 個半形字元。
  • 根據 Unicode 正規化表單 C 進行正規化處理。
  • 不得包含下列任一 ASCII 字元：「/」、「:」、「?」、「,」或「#」。
deliveryVehicleId

string

僅供輸出。執行此工作的車輛 ID。運送車輛 ID 有以下限制：

  • 必須是有效的萬國碼 (Unicode) 字串。
  • 長度上限為 64 個半形字元。
  • 根據 Unicode 正規化表單 C 進行正規化處理。
  • 不得包含下列任一 ASCII 字元：「/」、「:」、「?」、「,」或「#」。
plannedLocation

object (LocationInfo)

無法變更。完成工作的位置。此為 UNAVAILABLE Tasks 的選用項目，如用於其他工作，則為必要元素。
taskDuration

string (Duration format)

必要欄位。無法變更。在這個位置執行任務所需的時間。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」，例如："3.5s"。
targetTimeWindow

object (TimeWindow)

應完成工作的時間範圍。
journeySharingInfo

object (JourneySharingInfo)

僅供輸出。旅程共用特定欄位。狀態為 CLOSED 時不會填入。
taskTrackingViewConfig

object (TaskTrackingViewConfig)

設定工作追蹤功能的工作，用來指定要在什麼情況下向使用者顯示哪些資料元素。
attributes[]

object (TaskAttribute)

自訂工作屬性的清單。每個屬性都必須具備專屬金鑰。

類型

Task 的類型。

列舉
TYPE_UNSPECIFIED 預設，工作類型不明。
PICKUP 取貨工作是指領取客戶出貨時會採取的行動。自取或餵食器車輛應使用 SCHEDULED_STOP 類型。
DELIVERY 交付工作是指將運送資訊送到客戶手上的動作。站點或餵食器車輛下車地點應使用 SCHEDULED_STOP 類型。
SCHEDULED_STOP 排定的停止 Task 用於規劃用途。例如由送貨員車或倉庫出貨。不過，請勿將本產品用於消費者從消費者取貨或出貨的任何貨物。
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

如果剩餘的停靠站計數 <= leftStopCountThreshold，使用者就可以看到此資料元素。
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

如果抵達停靠站的預計到達時間 <= durationUntilEstimatedArrivalTimeThreshold，使用者便可看到此資料元素。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」，例如："3.5s"。
remainingDrivingDistanceMetersThreshold

integer

如果剩餘的行車距離 (公尺 <= leftDrivingDistanceMetersThreshold)，使用者就可以看到此資料元素。
always

boolean

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

boolean

如果設為 True，系統一律會對使用者隱藏這個資料元素，且不會設定閾值。這個欄位無法設為 false。

方法

batchCreate

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

create

 建立並傳回新的 Task 物件。

get

 取得 Task 的相關資訊。

list

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

patch

 更新「Task」資料。

search
(deprecated)

 已淘汰：請改用 GetTaskTrackingInfo。