Tạo nhiệm vụ vận chuyển

Tài liệu này giả định rằng bạn đã đọc hướng dẫn giới thiệu về [Nhiệm vụ theo lịch trình][1] trong phần Giới thiệu về Fleet Engine cũng như [Nhiệm vụ theo lịch trình là gì?][2] trong phần này.

Fleet Engine cho các nhiệm vụ theo lịch cung cấp nhiều danh mục nhiệm vụ:

  • Nhiệm vụ vận chuyển: Dùng cho các nhiệm vụ lái xe, bao gồm cả việc lấy hàng và giao hàng.
  • Nhiệm vụ không rảnh: Sử dụng cho những thời điểm tài xế không rảnh, chẳng hạn như khi nghỉ giải lao bắt buộc.
  • Tác vụ dừng theo lịch: Dùng cho các tác vụ không liên quan đến việc lái xe tại hộp thư hoặc địa điểm của khách hàng, chẳng hạn như thời gian vào toà nhà hoặc tìm điểm giao hàng.

Tài liệu này trình bày cách tạo nhiệm vụ lô hàng trên máy chủ của bạn. Đối với các loại việc cần làm khác, hãy xem bài viết Tạo các loại việc cần làm khác.

Trường nhiệm vụ vận chuyển

Phần này trình bày các trường nhiệm vụ cần thiết cho cả nhiệm vụ lấy hàng và giao hàng.

Các trường bắt buộc của nhiệm vụ

Đối với mỗi nhiệm vụ bạn tạo trong Công cụ quản lý hành trình và đội xe, bạn phải cung cấp các trường bắt buộc và cũng có thể cung cấp bất kỳ trường tuỳ chọn nào. Fleet Engine bỏ qua tất cả các trường khác và gửi một ngoại lệ nếu yêu cầu tạo nhiệm vụ cung cấp deliveryVehicleId được chỉ định. Để giao nhiệm vụ cho một xe, hãy sử dụng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem phần Cập nhật việc cần làm.

TrườngGiá trị
type

Đặt thành loại khớp với loại nhiệm vụ, là một trong các loại sau:

  • PICKUP
  • DELIVERY
  • SCHEDULED_STOP
  • UNAVAILABLE
state State.OPEN
task_id Mã việc cần làm duy nhất. Đây không được là số vận đơn của lô hàng. Nếu không có mã nhận dạng nhiệm vụ trong hệ thống, bạn có thể tạo một giá trị nhận dạng duy nhất trên toàn hệ thống (UUID). Để biết thông tin cụ thể, hãy xem phần Mã tác vụ.
tracking_id Chỉ dành cho nhiệm vụ PICKUP hoặc DELIVERY: Số hoặc giá trị nhận dạng mà bạn đang dùng để theo dõi một lô hàng. Đừng cung cấp trường này cho các nhiệm vụ không liên quan đến việc vận chuyển.
planned_location Chỉ dành cho việc cần làm PICKUP, DELIVERY hoặc SCHEDULED_STOP: Vị trí cần hoàn thành việc cần làm. Không bắt buộc đối với các tác vụ UNAVAILABLE.
task_duration Thời gian dự kiến để hoàn thành việc cần làm. Ví dụ: để tìm chỗ đỗ xe hoặc đi bộ đến địa điểm giao hàng.

Các trường không bắt buộc về nhiệm vụ vận chuyển

TrườngGiá trị
target_time_window Khoảng thời gian cần hoàn thành việc cần làm. Trường này không ảnh hưởng đến hành vi định tuyến.
task_tracking_view_config Chỉ các nhiệm vụ PICKUP hoặc DELIVERY: Cấu hình cho tính năng theo dõi nhiệm vụ, trong đó chỉ định những phần tử dữ liệu nào hiển thị cho người dùng cuối trong trường hợp nào.
attributes Danh sách các thuộc tính tuỳ chỉnh của nhiệm vụ. Mỗi thuộc tính phải có một khoá riêng biệt.

Tạo nhiệm vụ lấy hàng

Để sử dụng Công cụ quản lý đội xe nhằm theo dõi hoạt động của tài xế đến lấy hàng, hãy tạo một nhiệm vụ lấy hàng. Việc này bao gồm việc đặt thuộc tính loại tác vụ thành PICKUP. Ví dụ sau đây minh hoạ một lô hàng được lấy tại Grand Indonesia East Mall.

Các ví dụ sau đây cho thấy cách tạo nhiệm vụ lấy hàng bằng cách sử dụng [thư viện gRPC Java][4] hoặc cách tạo yêu cầu HTTP REST đến [CreateTask][5].

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.PICKUP)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have a task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

Để tạo một nhiệm vụ lấy hàng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> là giá trị nhận dạng riêng biệt của nhiệm vụ.

Tiêu đề của yêu cầu phải chứa trường Authorization có giá trị Bearer <token>, trong đó <token> do máy chủ của bạn cấp theo các nguyên tắc được mô tả trong [Vai trò của tài khoản dịch vụ][6] và [Mã thông báo web JSON][7].

Nội dung yêu cầu phải chứa một thực thể Task có các trường thích hợp được mô tả trong [Trường nhiệm vụ vận chuyển][8].

Ví dụ về lệnh curl:

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "PICKUP",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM

Tạo nhiệm vụ giao hàng

Để sử dụng Công cụ quản lý đội xe nhằm theo dõi hoạt động của tài xế giao hàng, hãy tạo một nhiệm vụ giao hàng. Việc này bao gồm việc đặt thuộc tính loại tác vụ thành DELIVERY. Ví dụ sau đây minh hoạ một lô hàng được giao đến Grand Indonesia East Mall.

Các ví dụ sau đây cho thấy cách tạo nhiệm vụ lấy hàng bằng cách sử dụng [thư viện gRPC Java][4] hoặc cách tạo yêu cầu HTTP REST đến [CreateTask][5].

gRPC

  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Task settings
  String parent = "providers/" + PROJECT_ID;
  Task task = Task.newBuilder()
    .setType(Task.Type.DELIVERY)
    .setState(Task.State.OPEN)
    .setTrackingId("my-tracking-id")
    .setPlannedLocation(               // Grand Indonesia East Mall
      LocationInfo.newBuilder().setPoint(
        LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setTaskDuration(
      Duration.newBuilder().setSeconds(2 * 60))
    .setTargetTimeWindow(
      TimeWindow.newBuilder()
        .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
        .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
    .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
    .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
    .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
    .build();

  // Task request
  CreateTaskRequest createTaskRequest =
    CreateTaskRequest.newBuilder()  // No need for the header
        .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
        .setTaskId("task-8241890")  // Task ID assigned by the Provider
        .setTask(task)              // Initial state
        .build();

  // Error handling
  // If Fleet Engine does not have task with that ID and the credentials of the
  // requestor pass, the service creates the task successfully.

  try {
    Task createdTask = deliveryService.createTask(createTaskRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case ALREADY_EXISTS:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

REST

Để tạo một nhiệm vụ lấy hàng từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST đến CreateTask:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> là giá trị nhận dạng riêng biệt của nhiệm vụ.

Tiêu đề của yêu cầu phải chứa trường Authorization có giá trị Bearer <token>, trong đó <token> do máy chủ của bạn cấp theo các nguyên tắc được mô tả trong [Vai trò của tài khoản dịch vụ][6] và [Mã thông báo web JSON][7].

Nội dung yêu cầu phải chứa một thực thể Task:

Ví dụ về lệnh curl:

 # Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
 # environment
 curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "type": "DELIVERY",
   "state": "OPEN",
   "trackingId": "${TRACKING_ID}",
   "plannedLocation": {
      "point": {
         "latitude": -6.195139,
         "longitude": 106.820826
      }
   },
   "taskDuration": "90s",
   "targetTimeWindow": {
     "startTime": "2023-03-29T21:00:00Z",
     "endTime": "2023-03-29T23:00:00Z"
   }
 }
 EOM
 ```

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

Bước tiếp theo

  • [Tạo các loại việc cần làm khác][13]
  • [Cập nhật việc cần làm][3]

[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks