REST Resource: providers.tasks

資源：Task

Delivery API 中的「工作」代表要追蹤的單一動作。一般而言，與出貨相關的「工作」和「中斷工作」之間會有區別。一項貨件可以有多個相關聯的 Tasks。舉例來說，您可以設定一個用於上車的任務，以及下車或轉車。此外，單一運送作業的不同工作也可由不同車輛處理。舉例來說，某輛車可以處理上車作業、將貨運載往中樞，另一輛車則負責將車子從中心到下車地點。

注意：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)

必要欄位。不可變動。定義任務的類型。例如中斷或運送。
state

enum (State)

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

enum (TaskOutcome)

工作的結果。
taskOutcomeTime

string (Timestamp format)

指出提供者設定 Task 結果的時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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 來說為選用項目，但所有其他 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 預設 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

定義使用者何時應看到 Task 資料元素的設定訊息。

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

如果剩餘的停靠站計數 <= otherStopCountThreshold ，會向使用者顯示這個資料元素。
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

如果抵達停靠站的預計到達時間 <= durationUntil 預估 ArrivalTimeThreshold ，使用者都能看到這個資料元素。

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

integer

如果剩餘的行車距離 (公尺 <= otherDrivingDistanceMetersThreshold) 就會向使用者顯示這個資料元素。
always

boolean

如果設為 True，使用者一律會看到沒有閾值的資料元素。這個欄位不得設為 false。
never

boolean

如果設為 True，系統就不會對使用者隱藏這個資料元素，且未設定門檻。這個欄位不得設為 false。

方法

batchCreate

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

create

 建立並傳回新的 Task 物件。

get

 取得 Task 的相關資訊。

list

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

patch

 更新「Task」資料。

search
(deprecated)

 已淘汰：請改用 GetTaskTrackingInfo。