Cập nhật trạng thái dừng

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

Như đã nêu trong phần Tác vụ định kỳ trong Fleet Engine Essentials, bạn tạo tác vụ và liên kết tác vụ đó với một điểm dừng của xe để mô hình hoá mối liên kết trong thế giới thực giữa tác vụ và vị trí mà xe dự kiến dừng để người lái xe có thể hoàn thành tác vụ.

Từ đó, bạn quản lý tiến trình của các nhiệm vụ trong suốt vòng đời của chúng bằng cách gửi thông tin cập nhật cho Fleet Engine để hệ thống này có thể thực hiện việc cập nhật trạng thái và định tuyến một cách hiệu quả nhất trong hành trình của nhiệm vụ. Một cách quan trọng để thực hiện việc này là cập nhật điểm dừng của xe khi xe đến gần, đến và rời khỏi điểm dừng. Điều này cho phép báo cáo và phân tích về tiến trình của nhiệm vụ cho cả nhà khai thác đội xe và người dùng cuối. Các nội dung cập nhật trạng thái này như sau:

  • Đang trên đường: Enum STATE cho VehicleStop sử dụng ENROUTE để cho biết điểm dừng tiếp theo trong danh sách hành trình của xe. Theo quan điểm của việc cần làm, điều này có nghĩa là mọi việc cần làm được liên kết với điểm dừng đều nằm ở vị trí tiếp theo trong danh sách cần hoàn thành.
  • Đã đến: Giá trị enum STATE cho VehicleStop sử dụng ARRIVED để cho biết rằng xe đã đến điểm dừng. Theo quan điểm của tác vụ, điều này có nghĩa là mọi tác vụ liên kết với điểm dừng đều đang được thực hiện.
  • Đã hoàn thành: Bạn đánh dấu một điểm dừng là đã hoàn thành bằng cách xoá điểm dừng đó khỏi danh sách các điểm dừng của xe. Khi bạn thực hiện việc này, Fleet Engine sẽ tự động đánh dấu tất cả các nhiệm vụ liên quan là ĐÃ ĐÓNG. Để biết thêm thông tin về cách đóng việc cần làm, hãy xem phần Hoàn tất việc cần làm.

Tài liệu này mô tả cách cập nhật trạng thái dừng bằng các phương pháp phía máy chủ. Bạn cũng có thể thực hiện việc này thông qua ứng dụng dành cho tài xế nếu bạn cho phép tài xế quản lý các việc cần làm bằng một thiết bị 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 đáng tin cậy duy nhất.

Xe đang trên đường đến điểm dừng

Hệ thống của bạn phải thông báo cho Fleet Engine khi xe bắt đầu đi theo chỉ dẫn đến điểm dừng tiếp theo. Việc này giúp cải thiện thời gian đến dự kiến và tính toán tuyến đường.

Các trường bắt buộc để ngừng cập nhật

Fleet Engine bỏ qua tất cả các trường khác trong thực thể cho thông báo.

TrườngGiá trị
remainingVehicleJourneySegments Danh sách các điểm dừng còn lại của xe, có trạng thái được đánh dấu là State.NEW.

Ví dụ về đường đi đến điểm dừng

Các ví dụ sau đây cho thấy cách thông báo cho Fleet Engine rằng một xe đang trên đường đến điểm dừng tiếp theo, bằng cách sử dụng thư viện gRPC Java hoặc lệnh gọi HTTP REST đến UpdateDeliveryVehicle.Tất cả các điểm dừng khác đều được đánh dấu là mới.

gRPC

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

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Vehicle settings
 DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
     // Next stop marked as ENROUTE
     .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.ENROUTE)))
     // All other stops marked as 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 updateDeliveryVehicleRequest =
   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à 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ụMã thông báo web theo chuẩn JSON.
  • Nội dung yêu cầu phải chứa một 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": "ENROUTE",
         "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

Xe đến trạm dừng

Bạn phải thông báo cho Fleet Engine khi xe đến một điểm dừng.

Các trường bắt buộc để ngừng cập nhật

Fleet Engine bỏ qua tất cả các trường khác trong thực thể cho thông báo.

TrườngGiá trị
remainingVehicleJourneySegments Danh sách các điểm dừng còn lại của xe, có trạng thái được đánh dấu là State.NEW.

Ví dụ về việc đến điểm dừng

Các ví dụ sau đây cho biết cách thông báo cho Fleet Engine rằng một chiếc xe đã đến điểm dừng, bằng cách sử dụng thư viện gRPC Java hoặc lệnh gọi HTTP REST đến UpdateDeliveryVehicle. Tất cả các điểm dừng khác đều được đánh dấu là mới.

gRPC

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

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // Marking the arrival at stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
         .setStop(VehicleStop.newBuilder()
             .setPlannedLocation(LocationInfo.newBuilder()
                 .setPoint(LatLng.newBuilder()
                     .setLatitude(37.7749)
                     .setLongitude(122.4194)))
             .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
             .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as 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))) // Remaining stops must be NEW.
      .build();

  // DeliveryVehicle request
  UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
    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à 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ụMã thông báo web theo chuẩn JSON.
  • Nội dung yêu cầu phải chứa một 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": "ARRIVED",
          "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

Xe dừng lại

Bạn phải thông báo cho Fleet Engine khi xe hoàn tất một điểm dừng. Điều này khiến tất cả các tác vụ liên kết với điểm dừng được đặt thành trạng thái ĐÓNG.

Các trường bắt buộc để ngừng cập nhật

Fleet Engine bỏ qua tất cả các trường khác trong thực thể cho thông báo.

TrườngGiá trị
remainingVehicleJourneySegments Danh sách các điểm dừng còn lại của xe, có trạng thái được đánh dấu là State.NEW. Điểm dừng đầu tiên trong danh sách phải có trạng thái được đánh dấu là State.ENROUTE.

Hoàn tất ví dụ về điểm dừng

Các ví dụ sau đây cho biết cách thông báo cho Fleet Engine rằng một chiếc xe đã đến điểm dừng, bằng cách sử dụng thư viện gRPC Java hoặc lệnh gọi HTTP REST đến UpdateDeliveryVehicle. Tất cả các điểm dừng khác đều được đánh dấu là mới.

gRPC

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

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
      // This stop has been completed and is commented out to indicate it
      // should be removed from the list of vehicle journey segments.
      // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
      //    .setStop(VehicleStop.newBuilder()
      //        .setPlannedLocation(LocationInfo.newBuilder()
      //            .setPoint(LatLng.newBuilder()
      //                .setLatitude(37.7749)
      //                .setLongitude(122.4194)))
      //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
      //        .setState(VehicleStop.State.ARRIVED)))
      // All other remaining stops marked as NEW.
      // The next stop could be marked as ENROUTE if the vehicle has begun
      // its journey to the next stop.
      .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next 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 updateDeliveryVehicleRequest =
    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=remaining_vehicle_journey_segments`
  • <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ụMã thông báo web theo chuẩn JSON.
  • Nội dung yêu cầu phải chứa một 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.3382,
             "longitude": 121.8863
           }
         },
         "tasks": [
           {
             "taskId": "${TASK2_ID}"
           }
         ]
       }
     }
   ]
 }
 EOM

Bước tiếp theo