本文假設您已閱讀「Fleet Engine 簡介」一節中排程工作的入門指南,以及本節的「什麼是排程工作?」。
針對排程工作,Fleet Engine 提供不同類別的工作:
- 運送工作:用於駕駛工作,包括自取和送貨服務。
- 無法使用的工作:適用於駕駛人無法使用的時間,例如需要休息的休息時間。
- 排定的停止工作:適用於放置於投遞箱或客戶地點的非行駛工作,例如進入建築物或尋找送貨點的時間。
本文說明如何在伺服器上建立「出貨」工作。如需瞭解其他工作類型,請參閱「建立其他工作類型」。
Shipment 工作欄位
本節將說明接送和取件任務所需的任務欄位。
必填工作欄位
針對您在 Fleet Engine 中建立的每項工作,您必須提供必要欄位,也可以選擇提供任何選用欄位。Fleet Engine 會忽略所有其他欄位,如果工作建立要求提供指定的 deliveryVehicleId
,就會擲回例外狀況。如要將工作指派給車輛,請使用 UpdateDeliveryVehicleRequest
。詳情請參閱「更新工作」。
欄位 | 值 |
---|---|
type |
設定為與工作類型相符的類型,可以是下列其中一項:
|
state |
State.OPEN |
task_id |
不重複的任務 ID。這不得為貨運項目的追蹤號碼。如果系統中沒有工作 ID,您可以產生通用專屬 ID (UUID)。詳情請參閱「工作 ID」。 |
tracking_id |
僅限 PICKUP 或 DELIVERY 工作:您用來追蹤運送狀態的號碼或 ID。請勿為非運送工作提供這個欄位。 |
plannedLocation |
僅限 PICKUP 、DELIVERY 或 SCHEDULED_STOP 工作:工作完成的位置。UNAVAILABLE 項工作不需要。 |
taskDuration |
預計完成這項工作的時間。例如尋找停車位,或步行前往交車地點。 |
選用運送工作欄位
欄位 | 值 |
---|---|
targetTimeWindow |
完成工作的時間範圍。這個欄位不會影響轉送行為。 |
task_tracking_view_config |
PICKUP 或 DELIVERY 工作任務 (僅限):工作追蹤的設定,可指定在何種情況下向使用者顯示哪些資料元素。 |
attributes |
自訂工作屬性清單。每個屬性都必須有專屬索引鍵。 |
建立運送商品提貨任務
如要使用 Fleet Engine 追蹤司機的收取貨物活動,請建立出貨取貨工作。這包括將工作類型屬性設為 PICKUP
。以下範例說明從 Grand Indonesia East Mall 取貨的情況。
以下範例說明如何使用 Java gRPC 程式庫建立運送提貨工作,或如何向 CreateTask
提出 HTTP REST 要求。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
如要從伺服器環境建立運送取貨工作,請向 CreateTask
發出 HTTP REST 呼叫:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> 是工作專屬 ID。
要求標頭必須包含「Authorization」欄位,其值為「Bearer <token>」,其中 <token> 是由伺服器根據「服務帳戶角色」和「JSON Web 權杖」中的指南所發出。
要求主體必須包含 Task
實體,並包含「Shipment task fields」中所述的適當欄位。
curl
指令範例:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
建立出貨交付工作
如要使用 Fleet Engine 追蹤司機運送貨物的活動,請建立貨物運送工作。這包括將工作類型屬性設為 DELIVERY
。以下範例說明運送至大印尼東購物中心的貨物。
以下範例說明如何使用 Java gRPC 程式庫建立運送取貨工作,或是如何向 CreateTask
發出 HTTP REST 要求。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
如要從伺服器環境建立運送取貨工作,請向 CreateTask
發出 HTTP REST 呼叫:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> 是工作專屬 ID。
要求標頭必須包含一個含有值 Bearer <token> 的「Authorization」欄位,其中 <token> 會根據服務帳戶角色和 JSON Web Token 中所述的準則,由伺服器核發。
要求主體必須包含 Task
實體:
curl
指令範例:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
```