REST Resource: providers.tasks

Tài nguyên: Việc cần làm

Một Tác vụ trong API Phân phối đại diện cho một hành động cần theo dõi. Nhìn chung, có sự khác biệt giữa Tác vụ liên quan đến lô hàng và Tác vụ nghỉ giải lao. Một lô hàng có thể liên kết với nhiều Việc cần làm. Ví dụ: có thể có một Tác vụ cho việc nhận hàng và một Tác vụ cho việc giao hàng hoặc chuyển hàng. Ngoài ra, các Nhiệm vụ khác nhau cho một lô hàng nhất định có thể được xử lý bằng các phương tiện khác nhau. Ví dụ: một xe có thể xử lý việc lấy hàng, vận chuyển lô hàng đến trung tâm, trong khi một xe khác vận chuyển cùng một lô hàng từ trung tâm đến địa điểm giao hàng.

Lưu ý: API gRPC và REST sử dụng các quy ước đặt tên trường khác nhau. Ví dụ: trường Task.journey_sharing_info trong API gRPC và trường Task.journeySharingInfo trong API REST tham chiếu đến cùng một trường.

Biểu diễn dưới dạng 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)
    }
  ]
}
Trường
name

string

Phải ở định dạng providers/{provider}/tasks/{task}.
type

enum (Type)

Bắt buộc. Không thể thay đổi. Xác định loại Tác vụ. Ví dụ: một lần nghỉ hoặc một lô hàng.
state

enum (State)

Bắt buộc. Trạng thái thực thi hiện tại của Tác vụ.
taskOutcome

enum (TaskOutcome)

Kết quả của việc cần làm.
taskOutcomeTime

string (Timestamp format)

Dấu thời gian cho biết thời điểm nhà cung cấp đặt kết quả của Task.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo Z và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ dời khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
taskOutcomeLocation

object (LocationInfo)

Vị trí đặt kết quả của Task. Giá trị này được cập nhật trong tasks.patch. Nếu nhà cung cấp không cập nhật rõ ràng giá trị này, thì theo mặc định, Công cụ quản lý đội xe sẽ điền giá trị này bằng vị trí xe xác định được gần đây nhất (vị trí thô).
taskOutcomeLocationSource

enum (TaskOutcomeLocationSource)

Cho biết giá trị của taskOutcomeLocation đến từ đâu.
trackingId

string

Không thể thay đổi. Trường này hỗ trợ việc lưu trữ mã nhận dạng để bạn có thể tránh sử dụng mối liên kết phức tạp. Bạn không thể đặt trackingId cho các Việc cần làm thuộc loại UNAVAILABLE và SCHEDULED_STOP. Những mã nhận dạng này phải tuân thủ các quy định hạn chế sau:

  • Phải là một chuỗi Unicode hợp lệ.
  • Giới hạn độ dài tối đa là 64 ký tự.
  • Được chuẩn hoá theo Unicode Normalization Form C (Biểu mẫu chuẩn hoá Unicode C).
  • Không được chứa bất kỳ ký tự ASCII nào sau đây: '/', ':', '?', ',' hoặc '#'.
deliveryVehicleId

string

Chỉ có đầu ra. Mã của xe đang thực thi Tác vụ này. Mã xe giao hàng phải tuân thủ các quy định hạn chế sau:

  • Phải là một chuỗi Unicode hợp lệ.
  • Giới hạn độ dài tối đa là 64 ký tự.
  • Được chuẩn hoá theo Unicode Normalization Form C (Biểu mẫu chuẩn hoá Unicode C).
  • Không được chứa bất kỳ ký tự ASCII nào sau đây: '/', ':', '?', ',' hoặc '#'.
plannedLocation

object (LocationInfo)

Không thể thay đổi. Vị trí mà Việc cần làm sẽ được hoàn thành. Không bắt buộc đối với Tác vụ UNAVAILABLE, nhưng bắt buộc đối với tất cả các Tác vụ khác.
taskDuration

string (Duration format)

Bắt buộc. Không thể thay đổi. Thời gian cần thiết để thực thi một Tác vụ tại vị trí này.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
targetTimeWindow

object (TimeWindow)

Khoảng thời gian cần hoàn thành tác vụ.
journeySharingInfo

object (JourneySharingInfo)

Chỉ có đầu ra. Các trường dành riêng cho tính năng chia sẻ hành trình. Không được điền khi trạng thái là CLOSED.
taskTrackingViewConfig

object (TaskTrackingViewConfig)

Cấu hình theo dõi tác vụ chỉ định những phần tử dữ liệu mà người dùng cuối có thể nhìn thấy trong những trường hợp nào.
attributes[]

object (TaskAttribute)

Danh sách các thuộc tính tuỳ chỉnh của Tác vụ. Mỗi thuộc tính phải có một khoá riêng biệt.

Loại

Loại công việc.

Enum
TYPE_UNSPECIFIED Theo mặc định, Loại tác vụ là không xác định.
PICKUP Công việc lấy hàng là hành động được thực hiện để lấy hàng của khách hàng. Bạn nên sử dụng loại SCHEDULED_STOP cho các điểm lấy hàng tại kho hoặc xe trung chuyển.
DELIVERY Tác vụ giao hàng là hành động được thực hiện để giao một lô hàng cho khách hàng cuối. Điểm trả xe tại kho hoặc điểm trung chuyển phải sử dụng loại SCHEDULED_STOP.
SCHEDULED_STOP Tác vụ dừng theo lịch được dùng cho mục đích lập kế hoạch. Ví dụ: điểm này có thể thể hiện việc lấy hàng hoặc trả hàng từ các xe trung chuyển hoặc kho. Bạn không nên sử dụng phương thức này cho bất kỳ lô hàng nào được khách hàng cuối đến lấy hoặc giao đến.
UNAVAILABLE Một Tác vụ có nghĩa là Xe không thể được bảo dưỡng. Ví dụ: điều này có thể xảy ra khi người lái xe nghỉ ngơi hoặc khi xe đang được đổ xăng.

TaskOutcomeLocationSource

Giá trị nhận dạng của nguồn đã điền sẵn taskOutcomeLocation.

Enum
TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED Kết quả của việc cần làm trước khi được đặt.
PROVIDER Nhà cung cấp đã chỉ định taskOutcomeLocation.
LAST_VEHICLE_LOCATION Nhà cung cấp không chỉ định taskOutcomeLocation, vì vậy, Công cụ quản lý đội xe đã sử dụng vị trí xe gần đây nhất được biết.

JourneySharingInfo

Các trường cụ thể khi chia sẻ hành trình.

Biểu diễn dưới dạng JSON 
{
  "remainingVehicleJourneySegments": [
    {
      object (VehicleJourneySegment)
    }
  ],
  "lastLocation": {
    object (DeliveryVehicleLocation)
  },
  "lastLocationSnappable": boolean
}
Trường
remainingVehicleJourneySegments[]

object (VehicleJourneySegment)

Thông tin theo dõi về các điểm dừng mà xe được chỉ định sẽ thực hiện trước khi hoàn tất Tác vụ này. Xin lưu ý rằng danh sách này có thể chứa các điểm dừng của các công việc khác.

Phân đoạn đầu tiên, Task.journey_sharing_info.remaining_vehicle_journey_segments[0] (gRPC) hoặc Task.journeySharingInfo.remainingVehicleJourneySegments[0] (REST), chứa thông tin tuyến đường từ vị trí đã biết gần đây nhất của người lái xe đến VehicleStop sắp tới. Thông tin tuyến đường hiện tại thường đến từ ứng dụng trình điều khiển, ngoại trừ một số trường hợp được ghi chú trong tài liệu về DeliveryVehicle.current_route_segment. Các phân khúc khác trong Task.journey_sharing_info.remaining_vehicle_journey_segments (gRPC) hoặc Task.journeySharingInfo.remainingVehicleJourneySegments (REST) được điền sẵn bằng Công cụ của đội xe. Các tệp này cung cấp thông tin tuyến đường giữa các VehicleStops còn lại.
lastLocation

object (DeliveryVehicleLocation)

Cho biết vị trí được báo cáo gần đây nhất của xe được chỉ định.
lastLocationSnappable

boolean

Cho biết liệu có thể chụp nhanh lastLocation của xe vào currentRouteSegment hay không. Giá trị này là False nếu lastLocation hoặc currentRouteSegment không tồn tại. Giá trị này do Công cụ của đội xe tính toán. Nội dung cập nhật của ứng dụng sẽ bị bỏ qua.

TaskTrackingViewConfig

Thông báo cấu hình xác định thời điểm người dùng cuối nhìn thấy một phần tử dữ liệu của một Tác vụ.

Biểu diễn dưới dạng JSON 
{
  "routePolylinePointsVisibility": {
    object (VisibilityOption)
  },
  "estimatedArrivalTimeVisibility": {
    object (VisibilityOption)
  },
  "estimatedTaskCompletionTimeVisibility": {
    object (VisibilityOption)
  },
  "remainingDrivingDistanceVisibility": {
    object (VisibilityOption)
  },
  "remainingStopCountVisibility": {
    object (VisibilityOption)
  },
  "vehicleLocationVisibility": {
    object (VisibilityOption)
  }
}
Trường
routePolylinePointsVisibility

object (VisibilityOption)

Trường chỉ định thời điểm các điểm của đường đa tuyến của tuyến đường có thể hiển thị. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.
estimatedArrivalTimeVisibility

object (VisibilityOption)

Trường chỉ định thời điểm có thể hiển thị thời gian đến dự kiến. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.
estimatedTaskCompletionTimeVisibility

object (VisibilityOption)

Trường chỉ định thời điểm có thể hiển thị thời gian hoàn thành công việc ước tính. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.
remainingDrivingDistanceVisibility

object (VisibilityOption)

Trường chỉ định thời điểm có thể hiển thị quãng đường lái xe còn lại. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.
remainingStopCountVisibility

object (VisibilityOption)

Trường chỉ định thời điểm có thể hiển thị số lượng điểm dừng còn lại. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.
vehicleLocationVisibility

object (VisibilityOption)

Trường chỉ định thời điểm có thể hiển thị vị trí của xe. Nếu bạn không chỉ định trường này, thì cấu hình chế độ hiển thị mặc định cấp dự án cho dữ liệu này sẽ được sử dụng.

VisibilityOption

Thông báo tuỳ chọn xác định thời điểm người dùng cuối nhìn thấy một phần tử dữ liệu.

Biểu diễn dưới dạng 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.
}
Trường
Trường hợp hợp nhất visibility_option. Chế độ hiển thị cụ thể đã chọn. visibility_option chỉ có thể là một trong những loại sau:
remainingStopCountThreshold

integer

Người dùng cuối có thể thấy phần tử dữ liệu này nếu số lượng điểm dừng còn lại <= remainingStopCountThreshold.
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

Người dùng cuối sẽ nhìn thấy phần tử dữ liệu này nếu ETA đến điểm dừng <= durationUntilEstimatedArrivalTimeThreshold.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
remainingDrivingDistanceMetersThreshold

integer

Người dùng cuối có thể thấy phần tử dữ liệu này nếu quãng đường lái xe còn lại tính bằng mét <= remainingDrivingDistanceMetersThreshold.
always

boolean

Nếu bạn đặt thành đúng, người dùng cuối sẽ luôn thấy phần tử dữ liệu này mà không có ngưỡng nào. Không thể đặt trường này thành false.
never

boolean

Nếu bạn đặt thành đúng, thì phần tử dữ liệu này sẽ luôn bị ẩn khỏi người dùng cuối mà không có ngưỡng nào. Không thể đặt trường này thành false.

Phương thức

batchCreate

 Tạo và trả về một loạt đối tượng Task mới.

create

 Tạo và trả về một đối tượng Task mới.

delete

 Xoá một Việc cần làm.

get

 Lấy thông tin về Task.

list

 Lấy tất cả Task đáp ứng tiêu chí lọc đã chỉ định.

patch

 Cập nhật dữ liệu Task.