REST Resource: providers.tasks

资源：任务

Delivery API 中的 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)

必需。不可变。定义任务的类型。例如，休息或运输。
state

enum (State)

必需。任务的当前执行状态。
taskOutcome

enum (TaskOutcome)

任务的结果。
taskOutcomeTime

string (Timestamp format)

指示提供方设置 Task 的结果的时间戳。

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
taskOutcomeLocation

object (LocationInfo)

设置 Task 的结果的位置。此值会在 tasks.patch 中更新。如果提供程序未明确更新此值，则车队引擎会默认使用上次已知车辆位置（原始位置）填充此值。
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)

必需。不可变。在此位置执行任务所需的时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
targetTimeWindow

object (TimeWindow)

任务应完成的时间范围。
journeySharingInfo

object (JourneySharingInfo)

仅限输出。与历程分享相关的字段。当状态为 CLOSED 时，不会填充。
taskTrackingViewConfig

object (TaskTrackingViewConfig)

任务跟踪的配置，用于指定在哪些情况下哪些数据元素可供最终用户查看。
attributes[]

object (TaskAttribute)

自定义任务属性的列表。每个属性都必须具有唯一键。

类型

任务的类型。

枚举
TYPE_UNSPECIFIED 默认情况下，任务类型为未知。
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。此值由车队引擎计算得出。系统会忽略来自客户端的更新。

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)

如果相应经停点的预计到达时间 <= durationUntilEstimatedArrivalTimeThreshold，则此数据元素会向最终用户显示。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
remainingDrivingDistanceMetersThreshold

integer

如果剩余行驶距离（以米为单位）小于等于 remainingDrivingDistanceMetersThreshold，最终用户会看到此数据元素。
always

boolean

如果设置为 true，则最终用户始终可以看到此数据元素，无需达到任何阈值。此字段无法设置为 false。
never

boolean

如果设为 true，系统会始终向最终用户隐藏此数据元素，且不设阈值。此字段无法设置为 false。

方法

batchCreate

 创建并返回一批新的 Task 对象。

create

 创建并返回新的 Task 对象。

delete

 删除单个任务。

get

 获取 Task 的相关信息。

list

 获取符合指定过滤条件的所有 Task。

patch

 更新 Task 数据。