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ề Tác vụ định kỳ trong phần Giới thiệu về Fleet Engine cũng như Tác vụ định kỳ là gì? trong phần này.

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

• Việc cần làm về lô hàng: Sử dụng cho các việc cần làm khi lái xe, bao gồm cả việc lấy và giao lô hàng.
• Việc không thể thực hiện: Sử dụng cho những thời điểm mà tài xế không thể thực hiện, chẳng hạn như khi cần nghỉ giải lao.
• Tác vụ dừng theo lịch: Sử dụng cho các tác vụ không lái xe tại hộp thư hoặc vị trí của khách hàng, chẳng hạn như thời gian vào toà nhà hoặc xác định vị trí giao hàng.

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

Các trường của nhiệm vụ vận chuyển

Phần này ghi lại các trường nhiệm vụ cần thiết cho cả nhiệm vụ đến lấy hàng và giao hàng.

Các trường bắt buộc của công việc

Đối với mỗi nhiệm vụ mà bạn tạo trong Fleet Engine, 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 không bắt buộc nào. Fleet Engine bỏ qua tất cả các trường khác và sẽ gửi một ngoại lệ nếu yêu cầu tạo nhiệm vụ cung cấp một deliveryVehicleId được chỉ định. Để giao việc cần làm cho một chiếc xe, hãy dùng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem bài viết Cập nhật việc cần làm.

Trường	Giá trị
type	Đặt thành loại khớp với loại tác vụ, là một trong những loại sau: PICKUP DELIVERY SCHEDULED_STOP UNAVAILABLE
state	State.OPEN
task_id	Mã nhận dạng duy nhất của việc cần làm. Đây không được là số theo dõi của lô hàng. Nếu không có mã nhận dạng tác vụ trong hệ thống, bạn có thể tạo một giá trị nhận dạng riêng biệt trên toàn cầu (UUID). Để biết thông tin cụ thể, hãy xem phần Mã nhận dạng tác vụ.
tracking_id	Chỉ dành cho các nhiệm vụ PICKUP hoặc DELIVERY: Số hoặc giá trị nhận dạng mà bạn đang sử dụng để theo dõi lô hàng. Đừng cung cấp trường này cho các việc cần làm không phải là việc vận chuyển.
planned_location	Chỉ có các nhiệm vụ PICKUP, DELIVERY hoặc SCHEDULED_STOP: Vị trí cần hoàn thành nhiệm vụ. 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 vị trí giao hàng.

Các trường không bắt buộc của việc cần làm về lô hàng

Trường	Giá trị
target_time_window	Khung thời gian mà bạn 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	PICKUP hoặc chỉ DELIVERY các tác vụ: Cấu hình để theo dõi tác vụ, trong đó chỉ định những phần tử dữ liệu mà người dùng cuối nhìn thấy trong những 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 việc cần làm để lấy hàng

Để sử dụng Fleet Engine theo dõi hoạt động của người lái xe đến lấy lô hàng, hãy tạo một nhiệm vụ lấy lô hàng. Thao tác này liên quan đến việc đặt thuộc tính loại nhiệm vụ thành PICKUP. Ví dụ sau đây minh hoạ việc lấy hàng tại Grand Indonesia East Mall.

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

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 việc cần làm để lấy hàng từ môi trường máy chủ, hãy thực hiện một 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 đề yêu cầu phải chứa một trường Authorization có giá trị Bearer <token>, trong đó <token> do máy chủ của bạn phát hành theo các nguyên tắc được mô tả trong Vai trò tài khoản dịch vụ và Mã thông báo web JSON.

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 của nhiệm vụ vận chuyển.

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

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place_id (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

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

Để sử dụng Fleet Engine theo dõi hoạt động của một tài xế đang giao hàng, hãy tạo một nhiệm vụ giao hàng. Việc này liên quan đến việc đặt thuộc tính loại nhiệm vụ thành DELIVERY. Ví dụ sau đây minh hoạ việc giao hàng đến Grand Indonesia East Mall.

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

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 việc cần làm để lấy hàng từ môi trường máy chủ, hãy thực hiện một 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 đề yêu cầu phải chứa một trường Authorization có giá trị Bearer <token>, trong đó <token> do máy chủ của bạn phát hành theo các nguyên tắc được mô tả trong Vai trò tài khoản dịch vụ và Mã thông báo web JSON.

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
 ```

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place_id (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

Bước tiếp theo

• Tạo các loại việc cần làm khác
• Cập nhật nhiệm vụ