更新停止状态

本文档假定您熟悉以下内容：

正如计划任务部分所述， Fleet Engine Essentials：您可以创建任务并将其与车辆相关联 停止作为对任务与实际任务之间的实际关联进行建模的一种方式， 车辆预计会停靠的位置，以便驾驶员能完成 任务。

之后，您可以按照以下方式管理任务在整个生命周期内的进度： 向 Fleet Engine 发送更新，以便其能够最有效地执行路由和状态 更新。实现这一目的的一个重要方法是 在车辆接近、到达和离开时停止停车。 这样可以针对双方的任务进度报告和分析 舰队操作员和最终用户。这些状态更新如下：

  • 路线中：VehicleStop 的 STATE 枚举使用 ENROUTE 来 表示经停点在车辆行程列表中下一个。 从任务的角度来看，它表示与停止相关的任何任务 列表中有待完成的下一个项目。
  • 已到达：VehicleStop 的 STATE 枚举使用 ARRIVED 来指示 车辆已抵达停车点。从任务的角度来看， 它表示与停止正在活跃处理的任何任务相关联。
  • 已完成：您可以将一个经停点从 。执行此操作后，Fleet Engine 会自动将 所有关联的任务均显示为“已关闭”。如需详细了解如何关闭任务，请参阅 最终确定任务。

本文档介绍了如何使用服务器端方法更新停止状态。您 您也可在驾驶员应用中完成这项操作 使用可信设备管理任务。请仅使用一种方法，以避免竞态 并保持单一可信来源。

车辆正在停靠的途中

当车辆开始导航到 下一站。这改善了预计到达时间和路线计算。

停止更新的必填字段

Fleet Engine 会忽略实体中用于通知的所有其他字段。

字段值
remainingVehicleJourneySegments 剩余车辆经停点列表，其中状态已标记为 State.NEW。

“行驶停止”示例

以下示例展示了如何通知 Fleet Engine 有车辆正在 在前往下一站的途中，使用 Java gRPC 库或 HTTP 对 UpdateDeliveryVehicle 进行 REST 调用。所有其他经停点均标记为新经停点。

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`
  • &lt;id&gt; 是任务的唯一标识符。
  • 请求标头必须包含字段 Authorization（值为 Bearer <token>，其中 <token> 由您的服务器发出 根据服务账号角色中所述的准则，以及 JSON Web 令牌。
  • 请求正文必须包含 DeliveryVehicle 实体：

示例 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

车辆已抵达停车点

Fleet Engine 必须在有车辆到达停车点时收到通知。

停止更新的必填字段

Fleet Engine 会忽略实体中用于通知的所有其他字段。

字段值
remainingVehicleJourneySegments 剩余车辆经停点列表，其中状态已标记为 State.NEW。

“到达站点”示例

以下示例展示了如何通知 Fleet Engine 有车辆已抵达 使用 Java gRPC 库或 HTTP REST 调用 UpdateDeliveryVehicle。所有其他经停点均被标记为新经停点。

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`
  • &lt;id&gt; 是任务的唯一标识符。
  • 请求标头必须包含字段 Authorization（值为 Bearer <token>，其中 <token> 由您的服务器发出 根据服务账号角色中所述的准则，以及 JSON Web 令牌。
  • 请求正文必须包含 DeliveryVehicle 实体：

示例 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

车辆停靠一站

当车辆停止时，Fleet Engine 必须收到通知。这会导致 将与停止相关的所有任务设置为“关闭”状态。

停止更新的必填字段

Fleet Engine 会忽略实体中用于通知的所有其他字段。

字段值
remainingVehicleJourneySegments 剩余车辆经停点列表，其中状态已标记为 State.NEW。 列表中的第一个经停点必须将其状态标记为 State.ENROUTE。

完成停止示例

以下示例展示了如何通知 Fleet Engine 有车辆已抵达 使用 Java gRPC 库或 HTTP REST 调用 UpdateDeliveryVehicle。所有其他经停点均被标记为新经停点。

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`
  • &lt;id&gt; 是任务的唯一标识符。
  • 请求标头必须包含字段 Authorization（值为 Bearer <token>，其中 <token> 由您的服务器发出 根据服务账号角色中所述的准则，以及 JSON Web 令牌。
  • 请求正文必须包含 DeliveryVehicle 实体：

示例 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

后续步骤