本文假設您瞭解如何建立及使用工作。以下提供具體範例,說明如何完成運送作業:
結束工作:結束出貨工作會將狀態變更為
CLOSED
,並表示該工作已不再有效。設定工作結果:工作關閉後,請將結果設為
SUCCEEDED
或FAILED
,完成工作。這是完成工作的重要環節,可確保系統在行程分享中顯示送達結果,並正確計算 Fleet Engine 服務的費用。
關閉工作
你可以透過下列方式結束工作:
- 更新車輛的停止狀態。從車輛中移除停靠點,這會連帶關閉與該停靠點相關的所有工作。詳情請參閱「更新停靠站狀態」。
- 從車輛停靠站清單中移除工作。這包括更新停靠站的工作清單,但清單中不再包含已完成的工作。請參閱「更新工作」一文中的「更新工作順序」一節。
- 將工作狀態設為
CLOSED
。這項操作只能針對未指派給車輛的工作執行。本節將說明這種做法。
工作關閉後可能無法重新開啟。
關閉工作並不代表工作成功或失敗。這表示系統不再將該工作視為進行中。如要指出工作的實際結果,並顯示在車隊追蹤和行程分享功能中,您必須指出工作的實際結果。請參閱下方的「設定工作結果」。
用於關閉工作的任務欄位
本節說明關閉工作時必須設定的欄位。車隊引擎會忽略實體中用於更新的其他所有欄位。
必填欄位 | 值 |
---|---|
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> 是工作的專屬 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 程式庫和 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> 是工作的專屬 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