Cập nhật nhiệm vụ xe giao hàng

Tài liệu này giả định rằng bạn đã quen thuộc với những nội dung sau:

Trong một tình huống giao hàng thực tế, các doanh nghiệp sẽ giao việc cần làm về lô hàng cho tài xế. Sau đó, tài xế sẽ dùng phương tiện để giao lô hàng đó cho người nhận tại một địa điểm đã lên kế hoạch, chẳng hạn như nhà ở hoặc phòng giao hàng trong một khu phức hợp. Bạn mô hình hoá việc này trong Fleet Engine bằng cách tạo một việc cần làm và gửi yêu cầu cập nhật phương tiện giao hàng. Sau đó, yêu cầu này sẽ cập nhật thực thể phương tiện bằng danh sách các điểm dừng cần di chuyển. Bạn chỉ định cho mỗi điểm dừng một danh sách các việc cần làm cần hoàn tất tại điểm dừng đó.

Bạn có thể cập nhật việc cần làm về phương tiện bất cứ lúc nào, nhưng thường thì bạn sẽ làm việc này cho các mục đích sau:

  • Lên lịch việc cần làm để phương tiện hoàn tất. Bạn có thể thực hiện việc này bằng yêu cầu cập nhật thêm một điểm dừng mới vào phương tiện hoặc bằng yêu cầu cập nhật thêm một việc cần làm mới vào một điểm dừng hiện có.
  • Cập nhật thứ tự của các việc cần làm hiện có liên kết với một điểm dừng phương tiện nhất định.
  • Thay đổi vị trí hoàn tất việc cần làm. Theo mặc định, Fleet Engine sẽ đánh dấu vị trí hoàn tất việc cần làm là cùng vị trí với điểm dừng phương tiện liên kết với việc cần làm đó. Nếu muốn, bạn có thể chỉ định các vị trí cụ thể cho từng việc cần làm. Ví dụ: bạn có thể có một điểm dừng phương tiện tại một khu phức hợp lớn để giao một số gói hàng, mỗi gói hàng được chỉ định một phòng giao thư cụ thể.
  • Đóng mọi việc cần làm đã chỉ định trước đó để loại bỏ chúng khỏi thứ tự cập nhật. Xem phần Hoàn tất việc cần làm để biết thông tin chi tiết.

Lên lịch hoặc thay đổi việc cần làm về giao hàng

Bạn có thể lên lịch hoặc thay đổi việc cần làm được chỉ định cho một phương tiện từ môi trường máy chủ hoặc bằng cách sử dụng Driver SDK nếu bạn cho phép tài xế quản lý việc cần làm bằng một thiết bị đáng tin cậy. Chỉ sử dụng một phương thức để tránh tình trạng tranh đua và duy trì một nguồn thông tin đáng tin cậy duy nhất.

Để chuyển một lô hàng từ phương tiện này sang phương tiện khác, hãy đóng việc cần làm ban đầu và tạo lại việc cần làm đó trước khi chỉ định cho một phương tiện khác. Nếu bạn cập nhật một phương tiện giao hàng để thêm một việc cần làm đã được chỉ định cho một phương tiện khác, bạn sẽ gặp lỗi.

Các trường bắt buộc để cập nhật việc cần làm

Phần này ghi lại các trường bắt buộc cần đặt khi cập nhật một việc cần làm cho một phương tiện. Không có trường không bắt buộc. Fleet Engine sẽ bỏ qua tất cả các trường khác trong thực thể để cập nhật.

Trường bắt buộcGiá trị
remainingVehicleJourneySegments Danh sách các phân đoạn hành trình cho các việc cần làm theo thứ tự thực hiện. Việc cần làm đầu tiên trong danh sách sẽ được thực hiện trước.
remainingVehicleJourneySegments[i].stop Điểm dừng cho việc cần làm i trong danh sách.
remainingVehicleJourneySegments[i].stop.plannedLocation Vị trí dự kiến cho điểm dừng.
remainingVehicleJourneySegments[i].stop.tasks Danh sách các việc cần làm tại điểm dừng phương tiện này.
remainingVehicleJourneySegments[i].stop.state State.NEW

Ví dụ về việc chỉ định việc cần làm

Các ví dụ sau đây cho biết cách sử dụng thư viện gRPC Java và lệnh gọi HTTP REST đến UpdateDeliveryVehicle để thêm 2 việc cần làm mới cho phương tiện.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String VEHICLE_ID = "vehicle-8241890";
 static final String TASK1_ID = "task-756390";
 static final String TASK2_ID = "task-849263";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Vehicle settings
 String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
 DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.7749)
                    .setLongitude(122.4194)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
            .setState(VehicleStop.State.NEW)))
     .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
        .setStop(VehicleStop.newBuilder()
            .setPlannedLocation(LocationInfo.newBuilder()
                .setPoint(LatLng.newBuilder()
                    .setLatitude(37.3382)
                    .setLongitude(121.8863)))
            .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
            .setState(VehicleStop.State.NEW)))
     .build();

 // DeliveryVehicle request
 UpdateDeliveryVehicleRequest updateDeliveryRequest =
   UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
       .setName(vehicleName)
       .setDeliveryVehicle(deliveryVehicle)
       .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
       .build();

 try {
   DeliveryVehicle updatedDeliveryVehicle =
       deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

 PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

  • <id> là mã nhận dạng riêng biệt cho một phương tiện giao hàng trong đội xe mà bạn dự định cập nhật thứ tự việc cần làm. Đây là mã nhận dạng mà bạn đã chỉ định khi tạo phương tiện.

  • Tiêu đề của yêu cầu phải chứa trường Authorization 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 bài viết Vai trò của 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 thực thể DeliveryVehicle

Ví dụ về lệnh curl:

  # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
  # environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
    "remainingVehicleJourneySegments": [
      {
        "stop": {
          "state": "NEW",
          "plannedLocation": {
            "point": {
              "latitude": 37.7749,
              "longitude": -122.084061
            }
          },
          "tasks": [
            {
              "taskId": "${TASK1_ID}"
            }
          ]
        }
      },
      {
        "stop": {
          "state": "NEW",
          "plannedLocation": {
            "point": {
              "latitude": 37.3382,
              "longitude": 121.8863
            }
          },
          "tasks": [
            {
              "taskId": "${TASK2_ID}"
            }
          ]
        }
      }
    ]
  }
  EOM

Bước tiếp theo