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ề Công việc theo lịch trình trong phần Giới thiệu về Fleet Engine cũng như bài viết Công việc theo lịch trình là gì? trong phần này.

Fleet Engine cho công việc theo lịch trình cung cấp nhiều danh mục công việc:

  • Công việc vận chuyển: Dùng cho các công việc lái xe, bao gồm cả việc lấy và giao hàng.
  • Công việc không có sẵn: Dùng cho những thời điểm mà tài xế không có sẵn, chẳng hạn như thời gian nghỉ bắt buộc.
  • Công việc dừng theo lịch trình: Dùng cho các công việc không phải lái xe tại các hộp thư thả hàng hoặc địa điểm của khách hàng, chẳng hạn như thời gian để vào một 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 công việc vận chuyển trên máy chủ. Đối với các loại công việc khác, hãy xem bài viết Tạo các loại công việc khác.

Trường công việc vận chuyển

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

Trường công việc bắt buộc

Đối với mọi công việc 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à gửi một ngoại lệ nếu yêu cầu tạo công việc cung cấp deliveryVehicleId được chỉ định. Để chỉ định công việc cho một xe, hãy sử dụng UpdateDeliveryVehicleRequest. Để biết thêm thông tin, hãy xem bài viết Cập nhật công việc.

TrườngGiá trị
type

Đặt thành loại phù hợp với loại công việc, một trong các loại sau:

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

Trường công việc vận chuyển không bắt buộc

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

Tạo công việc lấy hàng vận chuyển

Để sử dụng Fleet Engine theo dõi hoạt động của một tài xế lấy hàng vận chuyển, hãy tạo công việc lấy hàng vận chuyển. Việc này bao gồm việc đặt thuộc tính loại công việc thành PICKUP. Ví dụ sau đây minh hoạ việc lấy hàng vận chuyển từ Trung tâm thương mại Grand Indonesia East.

Các ví dụ sau đây cho biết cách tạo công việc đến lấy hàng vận chuyển bằng thư viện gRPC Java hoặc cách thực hiện yêu cầu HTTP REST tới 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 công việc lấy hàng vận chuyển từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST tới 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 cho công việc.

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 phát hành theo nguyên tắc được mô tả trong bài viết Vai trò tài khoản dịch vụ và JSON Web tokens.

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ông việc 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

Tạo công việc giao hàng vận chuyển

Để sử dụng Fleet Engine theo dõi hoạt động của một tài xế giao hàng vận chuyển, hãy tạo công việc giao hàng vận chuyển. Việc này bao gồm việc đặt thuộc tính loại công việc thành DELIVERY. Ví dụ sau đây minh hoạ việc giao hàng vận chuyển đến Trung tâm thương mại Grand Indonesia East.

Các ví dụ sau đây cho biết cách tạo công việc đến lấy hàng vận chuyển bằng thư viện gRPC Java hoặc cách thực hiện yêu cầu HTTP REST tới 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 công việc lấy hàng vận chuyển từ môi trường máy chủ, hãy thực hiện lệnh gọi HTTP REST tới 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 cho công việc.

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 phát hành theo nguyên tắc được mô tả trong bài viết Vai trò tài khoản dịch vụ và JSON Web tokens.

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

Bước tiếp theo