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

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 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 取貨工作是指從客戶取貨時採取的行動。Depot 或 Feeder 車輛上車時應使用 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)

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

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

integer

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

boolean

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

boolean

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

方法

batchCreate

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

create

 建立並傳回新的 Task 物件。

get

 取得 Task 的相關資訊。

list

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

patch

 更新 Task 資料。