REST Resource: providers.tasks

資源：Task

Delivery API 中的 工作 代表要追蹤的單一動作。一般而言，運送相關工作和中斷工作之間存在差異。同一則運送資訊可以有多個相關聯的工作。例如，一個上車和下車/轉乘的任務，此外，特定配送服務適用的不同工作也可以由不同車輛處理。舉例來說，某輛車可能處理上車問題、將貨物運送至中樞裝置，另一輛車從集線推動到下車地點。

注意：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 結果的時間戳記。

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 工作非必要，但所有其他工作皆為必要項目。
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 取貨工作是指從客戶取貨時採取的行動。Depot 或 Feeder 車輛上車時應使用 SCHEDULED_STOP 類型。
DELIVERY 「運送工作」是指出貨給消費者時採取的行動。Depot 或饋送器下車地點應使用 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

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

string (Duration format)

如果到達停靠站的預計到達時間 <= timeUntil 預估 ArrivalTimeThreshold，使用者可以看見此資料元素。

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

integer

如果剩餘的行車距離 (以公尺 <= leftoptimizeDistanceMetersThreshold) 顯示，使用者可以看見這個資料元素。
always

boolean

如果設為 true，使用者一律會在沒有閾值的情況下看見這項資料元素。這個欄位無法設為 false。
never

boolean

如果設為 True，使用者一律會在沒有閾值的情況下隱藏這個資料元素。這個欄位無法設為 false。

方法

batchCreate

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

create

 建立並傳回新的 Task 物件。

get

 取得 Task 的相關資訊。

list

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

patch

 更新 Task 資料。