REST Resource: providers.tasks

资源:任务

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)

Task 的结果。

taskOutcomeTime

string (Timestamp format)

指明提供程序设置 Task 结果的时间的时间戳。

时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例:"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,因此可以避免使用复杂的映射。您不能为 UNAVAILABLESCHEDULED_STOP 类型的任务设置 trackingId。这些 ID 存在以下限制:

  • 必须是有效的 Unicode 字符串。
  • 长度上限为 64 个字符。
  • 根据 Unicode 标准化形式 C 进行标准化。
  • 不得包含以下任何 ASCII 字符:“/”“:”“?”“,”或“#”。
deliveryVehicleId

string

仅限输出。执行此 Task 的车辆的 ID。送货车辆 ID 存在以下限制:

  • 必须是有效的 Unicode 字符串。
  • 长度上限为 64 个字符。
  • 根据 Unicode 标准化形式 C 进行标准化。
  • 不得包含以下任何 ASCII 字符:“/”“:”“?”“,”或“#”。
plannedLocation

object (LocationInfo)

不可变。将完成 Task 的位置。对于 UNAVAILABLE 任务为可选参数,但对于所有其他任务为必需参数。

taskDuration

string (Duration format)

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

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

targetTimeWindow

object (TimeWindow)

应完成任务的时间范围。

journeySharingInfo

object (JourneySharingInfo)

仅限输出。历程共享专用字段。当状态为 CLOSED 时,不会填充。

taskTrackingViewConfig

object (TaskTrackingViewConfig)

任务跟踪配置,用于指定在什么情况下最终用户可以看到哪些数据元素。

attributes[]

object (TaskAttribute)

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

类型

Task 的类型。

枚举
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 前将进行的停靠的跟踪信息。请注意,此列表可以包含其他任务的站点。

第一段 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。如果 lastLocationcurrentRouteSegment 不存在,则此值为 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)

如果到达站点的预计到达时间 <=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 数据。