Hoàn tất việc cần làm
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này giả định rằng bạn hiểu cách tạo và sử dụng các tác vụ. Nó cung cấp các ví dụ cụ thể về cách hoàn tất các việc cần làm trong quá trình vận chuyển như sau:
Đóng việc cần làm: Khi bạn đóng một việc cần làm liên quan đến lô hàng, trạng thái của việc cần làm đó sẽ thay đổi thành CLOSED và cho biết rằng việc cần làm đó không còn hoạt động nữa.
Đặt kết quả của công việc: Sau khi đóng một công việc, bạn sẽ hoàn tất công việc đó bằng cách đặt kết quả thành SUCCEEDED hoặc FAILED. Đây là một phần quan trọng trong việc hoàn tất một nhiệm vụ để cho thấy kết quả giao hàng trong tính năng chia sẻ hành trình và đảm bảo tính phí chính xác cho dịch vụ Fleet Engine.
Đóng việc cần làm
Bạn có thể đóng một việc cần làm theo những cách sau:
- Cập nhật trạng thái dừng của xe. Bạn xoá điểm dừng khỏi xe, do đó, tất cả các việc cần làm liên quan đến điểm dừng đó cũng sẽ bị đóng. Hãy xem phần Trạng thái dừng cập nhật để biết thông tin chi tiết.
- Xoá việc cần làm khỏi danh sách các điểm dừng của xe. Thao tác này liên quan đến việc cập nhật danh sách các việc cần làm cho điểm dừng, nhưng việc cần làm đã đóng sẽ không còn nằm trong danh sách nữa. Xem phần Cập nhật thứ tự của việc cần làm trong bài viết Cập nhật việc cần làm.
- Đặt trạng thái của việc cần làm thành
CLOSED. Bạn chỉ có thể thực hiện việc này trên những việc cần làm chưa được giao cho xe. Phần này trình bày phương pháp này.
Sau khi đóng một việc cần làm, bạn sẽ không thể mở lại việc đó.
Việc đóng một tác vụ không cho biết tác vụ đó có thành công hay không. Trạng thái này cho biết rằng tác vụ không còn được coi là đang diễn ra nữa. Để cho biết kết quả thực tế của một nhiệm vụ và hiển thị kết quả đó cho mục đích Theo dõi đội xe và chia sẻ hành trình, bạn phải cho biết kết quả thực tế của một nhiệm vụ. Xem phần Đặt kết quả của nhiệm vụ bên dưới.
Các trường nhiệm vụ để đóng nhiệm vụ
Phần này ghi lại các trường bắt buộc phải thiết lập khi đóng một tác vụ. Fleet Engine bỏ qua tất cả các trường khác trong thực thể để cập nhật.
| Trường bắt buộc |
Giá trị |
state |
State.CLOSED |
Đóng việc cần làm ngay
Các ví dụ sau đây cho thấy cách đặt một tác vụ chưa được chỉ định thành trạng thái đã đóng, trong gRPC hoặc bằng cách sử dụng lệnh gọi yêu cầu HTTP REST đến 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> là giá trị nhận dạng riêng biệt của nhiệm vụ.
- Tiêu đề yêu cầu phải chứa một trường Authorization 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 Vai trò tài khoản dịch vụ và Mã thông báo web theo chuẩn JSON.
- Bạn phải thêm một thực thể
Task vào nội dung yêu cầu
Ví dụ về lệnh 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
Đặt kết quả của việc cần làm
Để cho biết kết quả thực tế của một việc cần làm, bạn có thể đặt kết quả cho những việc cần làm đã đóng là SUCCEEDED hoặc FAILED. Bạn phải đóng một việc cần làm trước khi đặt kết quả của việc đó. Fleet Engine chỉ tính phí cho các nhiệm vụ giao hàng có trạng thái SUCCEEDED.
Thông tin chi tiết về kết quả của việc cần làm
Các tác vụ cũng cung cấp thêm thông tin chi tiết về kết quả của tác vụ. Bạn có thể đặt trực tiếp các chế độ cài đặt này và Fleet Engine sẽ tuân theo các chế độ cài đặt của bạn:
- Vị trí kết quả của nhiệm vụ: Fleet Engine tự động điền vị trí kết quả của nhiệm vụ bằng vị trí đã biết gần đây nhất của xe. Bạn có thể cung cấp thông tin này thay thế nếu muốn.
- Thời gian hoàn thành nhiệm vụ: Fleet Engine không điền sẵn trường này, nhưng bạn có thể thiết lập.
Bạn có thể sử dụng bất kỳ phương pháp nào sau đây để thiết lập task_outcome_location và task_outcome_time:
- Cập nhật các tham số này trong cùng một yêu cầu đặt kết quả của tác vụ.
- Cập nhật sau, sau khi bạn đã đặt kết quả của nhiệm vụ.
- Sửa đổi lại sau khi bạn đã đặt.
Fleet Engine ngăn chặn các nội dung cập nhật sau đây liên quan đến kết quả của nhiệm vụ:
- Bạn không thể sửa đổi kết quả của một việc cần làm sau khi đặt thành
SUCCEEDED hoặc FAILED.
- Bạn không thể đặt vị trí kết quả của việc cần làm hoặc thời gian kết quả của việc cần làm cho những việc cần làm chưa có kết quả được đặt.
Các trường việc cần làm để thiết lập kết quả
Phần này ghi lại các trường bắt buộc và không bắt buộc cần đặt khi đặt kết quả của một tác vụ. Fleet Engine bỏ qua các trường khác trong thực thể để cập nhật.
| Trường bắt buộc |
Giá trị |
taskOutcome |
Outcome.SUCCEEDED hoặc Outcome.FAILED |
| Trường không bắt buộc | Giá trị |
|---|
taskOutcomeLocation |
Địa điểm hoàn thành việc cần làm. Nếu bạn không đặt, Fleet Engine sẽ mặc định đặt giá trị này thành vị trí gần đây nhất của xe. |
taskOutcomeTime |
Dấu thời gian khi việc cần làm được hoàn thành. |
Ví dụ về kết quả của nhiệm vụ
Ví dụ sau đây cho biết cách sử dụng thư viện gRPC Java và lệnh gọi REST HTTP đến UpdateTask để đặt kết quả của một tác vụ thành SUCCEEDED và đặt vị trí hoàn thành tác vụ.
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> là giá trị nhận dạng riêng biệt của nhiệm vụ.
- Tiêu đề yêu cầu phải chứa một trường Authorization 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 Vai trò tài khoản dịch vụ và Mã thông báo web theo chuẩn JSON.
- Nội dung yêu cầu phải chứa một thực thể
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
Bước tiếp theo
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-31 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-31 UTC."],[[["\u003cp\u003eThis document explains how to finalize shipment tasks in Fleet Engine by closing them and setting their outcome to \u003ccode\u003eSUCCEEDED\u003c/code\u003e or \u003ccode\u003eFAILED\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eClosing a task indicates it is no longer in progress, while setting the outcome reflects the delivery result for billing and journey sharing.\u003c/p\u003e\n"],["\u003cp\u003eTasks can be closed by updating the vehicle's stop status, removing them from the vehicle's stop list, or setting their state to \u003ccode\u003eCLOSED\u003c/code\u003e if unassigned.\u003c/p\u003e\n"],["\u003cp\u003eThe task outcome, location, and time can be set using the \u003ccode\u003eUpdateTask\u003c/code\u003e method with appropriate fields and values, but the outcome cannot be changed once set.\u003c/p\u003e\n"]]],["To finalize shipment tasks, you must first close them, setting the `state` to `CLOSED`, which indicates the task is no longer active. Closing can be done by updating the vehicle's stop status, removing the task from the vehicle's stop list, or directly setting the task state. Once closed, set the `taskOutcome` to `SUCCEEDED` or `FAILED`, with optional details like `taskOutcomeLocation` and `taskOutcomeTime`. The task outcome is essential for journey sharing and billing. You can use gRPC or HTTP REST calls to accomplish both.\n"],null,["This document assumes you understand how to create and use tasks. It provides\nspecific examples for how to finalize shipment tasks as follows:\n\n- **Close a task** : Closing a shipment task changes its state to `CLOSED` and\n indicates that that task is no longer active.\n\n- **Set the task outcome** : Once a task is closed, you then finalize it by\n setting its outcome to either `SUCCEEDED` or `FAILED`. This is an important\n part of finalizing a task in order to show the delivery outcome in journey\n sharing and to ensure correct billing for the Fleet Engine service.\n\nClose a task\n\nYou can close a task in the following ways:\n\n- **Update the stop status for the vehicle** . You remove the stop from the vehicle, which in turn closes all tasks associated with the stop. See [Update stop status for details](/maps/documentation/mobility/fleet-engine/journeys/tasks/update-stops).\n- **Remove the task from the list of vehicle stops** . This involves updating the list of tasks for the stop, but with the closed task no longer part of the list. See Update task order in [Update tasks](/maps/documentation/mobility/fleet-engine/journeys/tasks/update-tasks).\n- **Set the task state to `CLOSED`**. This can only be done on tasks not assigned to vehicles. This section shows this approach.\n\nOnce you close a task, you may not reopen it.\n\u003e \u003e **Closing of a task does not indicate its success or failure** . It indicates\n\u003e \u003e that the task is no longer considered in progress. In order to indicate the\n\u003e \u003e actual outcome of a task and to have that displayed for Fleet Tracking and\n\u003e \u003e journey sharing purposes, you must indicate the actual outcome of a task. See\n\u003e \u003e [Set the task outcome](#set-task-outcome) below.\n\nTask fields for closing tasks\n\nThis section documents the required fields to set when closing a\ntask. Fleet engine ignores all other fields in the entity for the update.\n\n\u003cbr /\u003e\n\n| Required field | Value |\n|----------------|----------------|\n| `state` | `State.CLOSED` |\n\n\u003cbr /\u003e\n\nClose a task directly\n\nThe following examples show how to set an unassigned task to a closed state,\neither in gRPC or using an HTTP REST request call to `UpdateTask` \n\ngRPC \n\n static final String PROJECT_ID = \"my-delivery-co-gcp-project\";\n static final String TASK_ID = \"task-8241890\";\n\n DeliveryServiceBlockingStub deliveryService =\n DeliveryServiceGrpc.newBlockingStub(channel);\n\n // Task settings\n String taskName = \"providers/\" + PROJECT_ID + \"/tasks/\" + TASK_ID;\n Task task = Task.newBuilder()\n .setName(taskName)\n .setState(Task.State.CLOSED) // You can only directly CLOSE a\n .build(); // task that is NOT assigned to a vehicle.\n\n // Task request\n UpdateTaskRequest updateTaskRequest =\n UpdateTaskRequest.newBuilder() // No need for the header\n .setTask(task)\n .setUpdateMask(FieldMask.newBuilder().addPaths(\"state\"))\n .build();\n\n try {\n Task updatedTask = deliveryService.updateTask(updateTaskRequest);\n } catch (StatusRuntimeException e) {\n Status s = e.getStatus();\n switch (s.getCode()) {\n case NOT_FOUND:\n break;\n case PERMISSION_DENIED:\n break;\n }\n return;\n }\n\nREST\n\n`PATCH https://fleetengine.googleapis.com/v1/providers/\u003cproject_id\u003e/tasks/\u003cid\u003e?updateMask=state`\n\n- *\\\u003cid\\\u003e* is a unique identifier for the task.\n- The request header must contain a field *Authorization* with the value *Bearer \\\u003ctoken\\\u003e* , where *\\\u003ctoken\\\u003e* is issued by your server according to the guidelines described in [Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) and [JSON Web tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt).\n- You must include a `Task` entity in the request body\n\nExample `curl` command: \n\n # Set JWT, PROJECT_ID, and TASK_ID in the local environment\n curl -X PATCH \"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime\" \\\n -H \"Content-type: application/json\" \\\n -H \"Authorization: Bearer ${JWT}\" \\\n --data-binary @- \u003c\u003c EOM\n {\n \"state\": \"CLOSED\",\n \"taskOutcome\": \"SUCCEEDED\",\n \"taskOutcomeTime\": \"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\"\n }\n EOM\n\nSet the task outcome\n\nTo indicate the actual outcome of a task, you set the outcome for closed tasks\nto either `SUCCEEDED` or `FAILED`. A task must be closed before you set its\noutcome. Fleet Engine only charges for delivery tasks with a state of\n`SUCCEEDED`.\n\nTask outcome details\n\nTasks also provide additional details about the task outcome. You can set these\ndirectly and Fleet Engine respects your settings:\n\n- **Task outcome location**: Fleet Engine automatically fills in the task outcome location with the last known vehicle location. You can provide this instead if you prefer.\n- **Task outcome time**: Fleet Engine does not fill this field in, but is available for you to set.\n\nYou can use any of the following approaches to setting `task_outcome_location`\nand `task_outcome_time`:\n\n- **Update them in the same request** that sets the task outcome.\n- **Update them later**, after you have set task outcome.\n- **Modify them again** after they have been set.\n\nFleet Engine prevents the following updates related to task outcomes:\n\n- **You can't modify a task outcome once it is set** to either `SUCCEEDED` or `FAILED`.\n- **You can't set a task outcome location or outcome time** for tasks without a set outcome.\n\nTask fields for setting outcome\n\nThis section documents the required and optional fields to set when setting a\ntask outcome. Fleet Engine ignores other fields in the entity for the update.\n\n\u003cbr /\u003e\n\n| Required field | Value |\n|----------------|-----------------------------------------|\n| `taskOutcome` | `Outcome.SUCCEEDED` or `Outcome.FAILED` |\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Optional field | Value |\n|-----------------------|-----------------------------------------------------------------------------------------------------------------|\n| `taskOutcomeLocation` | The location where the task was completed. If not set, Fleet Engine defaults this to the last vehicle location. |\n| `taskOutcomeTime` | The timestamp when the task was completed. |\n\n\u003cbr /\u003e\n\nTask outcome examples\n\nThe following example shows how to use the [Java gRPC library](/maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks) and an HTTP\nREST call to `UpdateTask` to set a task outcome to `SUCCEEDED` and set the\nlocation where the task was completed. \n\ngRPC \n\n static final String PROJECT_ID = \"my-delivery-co-gcp-project\";\n static final String TASK_ID = \"task-8241890\";\n\n DeliveryServiceBlockingStub deliveryService =\n DeliveryServiceGrpc.newBlockingStub(channel);\n\n // Task settings\n String taskName = \"providers/\" + PROJECT_ID + \"/tasks/\" + TASK_ID;\n Task task = Task.newBuilder()\n .setName(taskName)\n .setTaskOutcome(TaskOutcome.SUCCEEDED)\n .setTaskOutcomeTime(now())\n .setTaskOutcomeLocation( // Grand Indonesia East Mall\n LocationInfo.newBuilder().setPoint(\n LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))\n .build();\n\n // Task request\n UpdateTaskRequest updateTaskRequest =\n UpdateTaskRequest.newBuilder() // No need for the header\n .setTask(task)\n .setUpdateMask(FieldMask.newBuilder().addPaths(\"task_outcome\", \"task_outcome_time\", \"task_outcome_location\"))\n .build();\n\n try {\n Task updatedTask = deliveryService.updateTask(updateTaskRequest);\n } catch (StatusRuntimeException e) {\n Status s = e.getStatus();\n switch (s.getCode()) {\n case NOT_FOUND:\n break;\n case PERMISSION_DENIED:\n break;\n }\n return;\n }\n\nREST\n\n`PATCH https://fleetengine.googleapis.com/v1/providers/\u003cproject_id\u003e/tasks/\u003cid\u003e?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`\n\n- *\\\u003cid\\\u003e* is a unique identifier for the task.\n- The request header must contain a field *Authorization* with the value *Bearer \\\u003ctoken\\\u003e* , where *\\\u003ctoken\\\u003e* is issued by your server according to the guidelines described in [Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) and [JSON Web tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt).\n- The request body must contain a `Task` entity.\n\n # Set JWT, PROJECT_ID, and TASK_ID in the local environment\n curl -X PATCH \"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation\" \\\n -H \"Content-type: application/json\" \\\n -H \"Authorization: Bearer ${JWT}\" \\\n --data-binary @- \u003c\u003c EOM\n {\n \"taskOutcome\": \"SUCCEEDED\",\n \"taskOutcomeTime\": \"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\",\n \"taskOutcomeLocation\": {\n \"point\": {\n \"latitude\": -6.195139,\n \"longitude\": 106.820826\n }\n }\n }\n EOM\n\nWhat's next\n\n- [Find tasks](/maps/documentation/mobility/fleet-engine/journeys/tasks/find-tasks)"]]
