完成任务

本文档假定您了解如何创建和使用任务。它提供了有关如何完成发货任务的具体示例，如下所示：

  • 关闭任务：关闭发货任务会将其状态更改为 CLOSED 并 表明该任务不再处于活跃状态。

  • 设置任务结果：关闭任务后，您可以通过 将任务结果设置为 SUCCEEDED 或 FAILED 来完成任务。这是完成任务的重要环节，以便在行程分享中显示配送结果，并确保 Fleet Engine 服务的结算正确无误。

关闭任务

您可以通过以下方式关闭任务：

  • 更新车辆的停靠状态 。您从车辆中移除停靠点，这反过来会关闭与该停靠点关联的所有任务。如需了解详情，请参阅 更新停靠状态。
  • 从车辆停靠点列表中移除任务 。这涉及更新停靠点的任务列表，但已关闭的任务不再是列表的一部分。请参阅更新任务中的更新任务顺序。
  • 将任务状态设置为 CLOSED。此操作只能对未分配给车辆的任务执行。本部分将介绍这种方法。

关闭任务后，您无法重新打开它。

关闭任务并不表示任务成功或失败 。它表示任务不再被视为正在进行中。为了表明任务的实际结果，并让 Fleet Tracking 和行程分享显示该结果，您必须指明任务的实际结果。请参阅下文的 设置任务结果。

用于关闭任务的任务字段

本部分介绍了关闭任务时需要设置的必填字段。对于更新，Fleet Engine 会忽略实体中的所有其他字段。

必填字段 值
state State.CLOSED

直接关闭任务

以下示例展示了如何使用 gRPC 或通过 HTTP REST 请求调用 UpdateTask 将未分配的任务设置为关闭状态

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TASK_ID = "task-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task settings
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 Task task = Task.newBuilder()
   .setName(taskName)
   .setState(Task.State.CLOSED) // You can only directly CLOSE a
   .build();                    // task that is NOT assigned to a vehicle.

 // Task request
 UpdateTaskRequest updateTaskRequest =
   UpdateTaskRequest.newBuilder()  // No need for the header
       .setTask(task)
       .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
       .build();

 try {
   Task updatedTask = deliveryService.updateTask(updateTaskRequest);
 } 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>/tasks/<id>?updateMask=state

  • <id> 是任务的唯一标识符。
  • 请求标头必须包含一个字段 Authorization，其值为 Bearer <token>，其中 <token> 由您的服务器 根据服务账号角色和 JSON Web 令牌中所述的准则颁发。
  • 您必须在请求正文中添加 Task 实体

示例 curl 命令：

 # Set JWT, PROJECT_ID, and TASK_ID in the local environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "state": "CLOSED",
   "taskOutcome": "SUCCEEDED",
   "taskOutcomeTime": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 }
 EOM

设置任务结果

如需指明任务的实际结果，请将已关闭任务的结果设置为 SUCCEEDED 或 FAILED。您必须先关闭任务，然后才能设置其结果。Fleet Engine 仅对状态为 SUCCEEDED 的配送任务收费。

任务结果详情

任务还提供有关任务结果的其他详细信息。您可以直接设置这些信息，Fleet Engine 会遵循您的设置：

  • 任务结果位置：Fleet Engine 会自动使用车辆的最新已知位置填充任务 结果位置。如果您愿意，也可以自行提供此信息。
  • 任务结果时间：Fleet Engine 不会填充此字段，但您可以自行设置。

您可以使用以下任一方法来设置 task_outcome_location 和 task_outcome_time：

  • 在设置任务结果的同一请求中更新它们 。
  • 在设置任务结果后更新它们。
  • 在设置后再次修改它们 。

Fleet Engine 会阻止以下与任务结果相关的更新：

  • 您无法修改已设置为 SUCCEEDED 或 FAILED 的任务结果。
  • 您无法为没有 设置结果的任务设置任务结果位置或结果时间。

用于设置结果的任务字段

本部分介绍了设置任务结果时需要设置的必填字段和选填字段。对于更新，Fleet Engine 会忽略实体中的其他字段。

必填字段 值
taskOutcome Outcome.SUCCEEDED 或 Outcome.FAILED

选填字段值
taskOutcomeLocation 任务完成的位置。如果未设置，Fleet Engine 会默认将其设置为车辆的最新位置。
taskOutcomeTime 任务完成时的时间戳。

任务结果示例

以下示例展示了如何使用 Java gRPC 库和 HTTP REST 调用 UpdateTask 将任务结果设置为 SUCCEEDED，并设置任务完成的 位置。

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TASK_ID = "task-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task settings
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 Task task = Task.newBuilder()
   .setName(taskName)
   .setTaskOutcome(TaskOutcome.SUCCEEDED)
   .setTaskOutcomeTime(now())
   .setTaskOutcomeLocation(               // Grand Indonesia East Mall
     LocationInfo.newBuilder().setPoint(
       LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
   .build();

 // Task request
 UpdateTaskRequest updateTaskRequest =
   UpdateTaskRequest.newBuilder()  // No need for the header
       .setTask(task)
       .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
       .build();

 try {
   Task updatedTask = deliveryService.updateTask(updateTaskRequest);
 } 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>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation

  • <id> 是任务的唯一标识符。
  • 请求标头必须包含一个字段 Authorization，其值为 Bearer <token>，其中 <token> 由您的服务器 根据服务账号角色和 JSON Web 令牌中所述的准则颁发。
  • 请求正文必须包含 Task 实体。
 # Set JWT, PROJECT_ID, and TASK_ID in the local environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "taskOutcome": "SUCCEEDED",
   "taskOutcomeTime": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
   "taskOutcomeLocation": {
     "point": {
       "latitude": -6.195139,
       "longitude": 106.820826
     }
   }
 }
 EOM

后续步骤