完成工作

本文假設您瞭解如何建立及使用工作。以下提供具體範例，說明如何完成運送作業：

  • 結束工作：結束出貨工作會將狀態變更為 CLOSED，並表示該工作已不再有效。

  • 設定工作結果：工作關閉後，請將結果設為 SUCCEEDED 或 FAILED，這是完成工作的重要環節，可讓系統在行程分享中顯示送達結果，並確保 Fleet Engine 服務的帳單正確無誤。

關閉工作

你可以透過下列方式結束工作：

  • 更新車輛的停止狀態。從車輛中移除停靠點，系統會連帶關閉與該停靠點相關聯的所有工作。詳情請參閱「更新停靠站狀態」。
  • 從車輛停靠點清單中移除工作。這包括更新停靠點的工作清單，但清單中不再包含已完成的工作。請參閱「更新工作」一文中的「更新工作順序」一節。
  • 將工作狀態設為 CLOSED。這項操作只能針對未指派給車輛的工作執行。本節將說明這種做法。

工作關閉後可能無法重新開啟。

關閉工作並不會指出工作是否成功。這表示系統不再將該工作視為進行中。如要指出工作實際結果，並顯示在車隊追蹤和行程分享功能中，您必須指出工作的實際結果。請參閱下方的「設定工作結果」。

用於關閉工作的任務欄位

本節說明關閉工作時必須設定的欄位。車隊引擎會忽略實體中用於更新的其他所有欄位。

必填欄位 值
state State.CLOSED

直接結束工作

下列範例說明如何使用 gRPC 或對 UpdateTask 發出 HTTP REST 要求呼叫，將未指派的工作設為已完成狀態。

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> 是工作的專屬 ID。
  • 要求標頭必須包含「Authorization」欄位，值為「Bearer <token>」，其中「<token>」是由伺服器根據「服務帳戶角色」和「JSON Web Token」中說明的準則發出。
  • 要求主體中必須包含 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 程式庫和對 UpdateTask 發出的 HTTP REST 呼叫，將工作結果設為 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> 是工作的專屬 ID。
  • 要求標頭必須包含「Authorization」欄位，值為「Bearer <token>」，其中「<token>」是由伺服器根據「服務帳戶角色」和「JSON Web Token」中說明的準則發出。
  • 要求主體必須包含 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

後續步驟