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:

  • [Tạo nhiệm vụ vận chuyển][1]
  • Phần giới thiệu về [Việc cần làm theo lịch][3], trong đó trình bày chi tiết mối quan hệ giữa việc cần làm, điểm dừng và xe.

Như đã nêu trong phần [Nhiệm vụ theo lịch][3] trong Kiến thức cơ bản về Fleet Engine, bạn tạo nhiệm vụ và liên kết nhiệm vụ đó với một điểm dừng của xe để mô hình hoá mối liên kết thực tế giữa nhiệm vụ và vị trí mà xe dự kiến sẽ dừng để tài xế có thể hoàn thành nhiệm 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 đến Fleet Engine để công cụ này có thể thực hiện tốt nhất việc định tuyến và cập nhật trạng thái trong suốt 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 thực hiện nhiệm vụ cho cả Nhà điều hành đội xe và người dùng cuối. Các trạng thái cập nhật này như sau:

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

Tài liệu này mô tả cách cập nhật trạng thái điểm 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 từ ứng dụng của tài xế nếu bạn cho phép tài xế quản lý nhiệm vụ bằng một thiết bị tin cậy. Chỉ sử dụng một phương thức để tránh tình huống tương tranh 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 di chuyển đến điểm dừng tiếp theo. Việc này giúp cải thiện kết quả tính toán thời gian đến dự kiến và tuyến đường.

Các trường bắt buộc đối với thông tin cập nhật về điểm dừng

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ề điểm dừng trên đường đi

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][5] hoặc lệnh gọi REST HTTP đế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 đề 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 cấp theo hướng dẫn được mô tả trong [Vai trò của tài khoản dịch vụ][6] và [Mã thông báo web JSON][6].
  • 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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

Xe đến điểm dừng

Fleet Engine phải được thông báo khi xe đến một điểm dừng.

Các trường bắt buộc đối với thông tin cập nhật về điểm dừng

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 thấy cách thông báo cho Fleet Engine rằng một xe đã đến điểm dừng, bằng cách sử dụng [thư viện gRPC Java][5] 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 đề 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 cấp theo hướng dẫn được mô tả trong [Vai trò của tài khoản dịch vụ][6] và [Mã thông báo web JSON][6].
  • 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 hoàn tất một điểm dừng

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

Các trường bắt buộc đối với thông tin cập nhật về điểm dừng

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.

Ví dụ về việc hoàn tất một đ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 đã đến điểm dừng, bằng cách sử dụng [thư viện gRPC Java][5] 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 đề 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 cấp theo hướng dẫn được mô tả trong [Vai trò của tài khoản dịch vụ][6] và [Mã thông báo web JSON][6].
  • 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

placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place

Bước tiếp theo

  • [Hoàn tất việc cần làm][4]

[1]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks [3]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [4]: /maps/documentation/mobility/fleet-engine/journeys/tasks/finalize-tasks [5]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts