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

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

• Tạo việc cần làm về lô hàng
• Phần giới thiệu về Công việc theo lịch, trình bày chi tiết mối quan hệ giữa các công việc, điểm dừng và xe.

Như đã nêu trong phần Tác vụ được lên lịch trong Kiến thức cơ bản về công cụ quản lý đội xe, bạn tạo các tác vụ và liên kết các tác vụ đó với một điểm dừng xe để mô hình hoá mối liên kết thực tế giữa tác vụ và vị trí dự kiến xe sẽ dừng để người lái xe có thể hoàn thành tác vụ.

Từ đó, bạn có thể quản lý tiến trình của các tác 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 Công cụ của đội xe để công cụ này có thể thực hiện tốt nhất việc cập nhật trạng thái và định tuyến trong suốt hành trình của tác vụ. Một cách chính để thực hiện việc này là cập nhật điểm dừng 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ông việc cho cả người vận hành và người dùng cuối. Sau đây là nội dung cập nhật trạng thái:

• Đ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 cho hành trình của xe. Từ 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 sẽ là tác vụ tiếp theo trong danh sách cần hoàn thành.
• Đã đến: Enum STATE cho VehicleStop sử dụng ARRIVED để cho biết rằng xe đã đến điểm dừng. Từ 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 đang được xử lý tích cực.
• Đã 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 như vậy, Công cụ của đội xe sẽ tự động đánh dấu tất cả các tác vụ được liên kết là ĐÃ KHOÁ. Để biết thêm thông tin chi tiết 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 từ ứng dụng trình điều khiển nếu cung cấp cho trình điều khiển khả năng quản lý các tác vụ 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 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 Công cụ quản lý đội xe khi xe bắt đầu chỉ đường đến điểm dừng tiếp theo. Điều này giúp cải thiện tính toán thời gian đến và tuyến đường.

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

Công cụ của Fleet sẽ bỏ qua tất cả các trường khác trong thực thể cho thông báo.

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

Ví dụ về điểm dừng trên tuyến

Các ví dụ sau đây cho biết cách thông báo cho Công cụ của đội xe 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 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 web JSON.
• Nội dung yêu cầu phải chứa một thực thể DeliveryVehicle:

Ví dụ về lệnh curl:

Lưu ý: Lệnh này sẽ ghi đè mọi remainingVehicleJourneySegments đã đặt trên xe giao hàng.

 # 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

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place_id (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

Xe đến điểm dừng

Bạn phải thông báo cho Công cụ quản lý đội xe khi một xe đến điểm dừng.

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

Công cụ của Fleet sẽ bỏ qua tất cả các trường khác trong thực thể cho thông báo.

Trường	Giá trị
remainingVehicleJourneySegments	Danh sách các điểm dừng còn lại của xe, trạng thái của các điểm dừng này đượ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 Công cụ của đội xe rằng một 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 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 web JSON.
• Nội dung yêu cầu phải chứa một thực thể DeliveryVehicle:

Ví dụ về lệnh curl:

Lưu ý: Lệnh này sẽ ghi đè mọi remainingVehicleJourneySegments đã được đặt trên xe giao hàng.

  # 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

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place_id (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

Xe hoàn tất một điểm dừng

Bạn phải thông báo cho Công cụ quản lý đội xe khi một 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 ĐÃ KHOÁ.

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

Công cụ của Fleet sẽ bỏ qua tất cả các trường khác trong thực thể cho thông báo.

Trường	Giá trị
remainingVehicleJourneySegments	Danh sách các điểm dừng còn lại của xe, trạng thái của các điểm dừng này được đánh dấu là State.NEW. Trạ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 Công cụ của đội xe rằng một 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 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 web JSON.
• Nội dung yêu cầu phải chứa một thực thể DeliveryVehicle:

Ví dụ về lệnh curl:

Lưu ý: Lệnh này sẽ ghi đè mọi remainingVehicleJourneySegments đã được đặt trên xe giao hàng.

 # 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

Thử nghiệm: Là một tính năng thử nghiệm, trường TerminalLocation (gRPC hoặc REST) hiện hỗ trợ việc sử dụng place_id (gRPC hoặc REST), cùng với hoặc thay cho LatLng.

Bước tiếp theo

• Hoàn tất công việc