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) 中的其他细分由车队引擎填充。它们提供其余 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 对象。

get

 获取 Task 的相关信息。

list

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

patch

 更新 Task 数据。