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ụ được lên lịch trong phần Giới thiệu về Công cụ của đội xe cũng như Tác vụ được lên lịch là gì? trong phần này.

Fleet Engine dành cho các nhiệm vụ theo lịch cung cấp nhiều loại nhiệm vụ:

  • Nhiệm vụ vận chuyển: Dùng để lái xe, bao gồm cả việc nhận và giao hàng.
  • Tác vụ không có mặt: Dùng cho những thời điểm người lái xe không thể sử dụng, chẳng hạn như khi có giờ nghỉ bắt buộc.
  • Nhiệm vụ dừng theo lịch: Dùng cho các nhiệm vụ không phải lái xe tại hộp thả xuống hoặc tại vị trí của khách hàng, chẳng hạn như thời gian đi vào một toà nhà hoặc xác định điểm giao hàng.

Tài liệu này trình bày cách tạo tác vụ shipment (đơn hàng) trên máy chủ của bạn. Đối với các loại tác vụ khác, hãy xem phần Tạo các loại tác vụ khác.

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

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

Trường việc cần làm bắt buộc

Đối với mỗi nhiệm vụ bạn tạo trong Fleet Engine, bạn phải cung cấp các trường bắt buộc, đồng thời có thể cung cấp bất kỳ trường nào không bắt buộc. Fleet Engine bỏ qua mọi trường khác và gửi ra một trường hợp ngoại lệ nếu yêu cầu tạo tác vụ cung cấp deliveryVehicleId được chỉ định. Để giao việc cần làm 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 phù hợp với loại tác vụ, là một trong các loại sau:

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

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

TrườngGiá trị
targetTimeWindow Khoảng thời gian hoàn thành tác vụ. Trường này không ảnh hưởng đến hoạt động định tuyến.
task_tracking_view_config Chỉ công việc PICKUP hoặc DELIVERY: Cấu hình để theo dõi công việc chỉ định phần tử dữ liệu nào sẽ 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 công việc tuỳ chỉnh. Mỗi thuộc tính phải có một khoá duy nhất.

Tạo việc cần làm để lấy hàng

Để sử dụng Fleet Engine nhằm theo dõi hoạt động của người lái xe để lấy hàng, hãy tạo một nhiệm vụ đến lấy hàng. Việc này liên quan đến việc đặt thuộc tính loại tác 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 minh hoạ cách tạo nhiệm vụ đến lấy hàng để vận chuyển bằng thư viện Java gRPC hoặc cách gửi 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 tác 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>

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ.

Tiêu đề yêu cầu phải chứa một trường Uỷ quyền với giá trị Bearer <token>, trong đó <token> do máy chủ của bạn cấp theo 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.

Phần 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 Các trường tác 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

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

Để sử dụng Công cụ xe cộ theo dõi hoạt động của người lái xe đang giao hàng, hãy tạo một nhiệm vụ giao hàng. Việc này bao gồm đặ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 biết cách tạo một tác vụ lấy hàng bằng cách sử dụng thư viện gRPC Java hoặc cách tạo một 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 tác 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>

&lt;id&gt; là giá trị nhận dạng duy nhất của tác vụ.

Tiêu đề yêu cầu phải chứa trường Authorization (Uỷ quyền) 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 phần Vai trò của tài khoản dịch vụ và Mã thông báo xác thực web JSON.

Phần nội dung yêu cầu phải chứa 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