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」資料。