本文件假設您已閱讀 入門指南 「Fleet Engine 簡介」一節中的排程工作 您會看到「什麼是排程工作?」。
適用於排程工作的 Fleet Engine 提供下列廣泛的工作類別:
- 運送工作:用於駕駛工作,包括自取和送貨 出貨。
- 無法提供服務的任務:用於司機無法提供服務的時間,例如休息時間。
- 排定的停止工作:適用於放置於投遞箱或客戶端的非駕駛工作 位置,例如輸入建築物或尋找送貨地點的時間。
本文件將說明如何在伺服器上建立非出貨工作。適用對象 運送工作類型,請參閱「建立運送工作」。
非駕駛任務的工作欄位
本節記錄這兩種服務都無法使用所需的工作欄位 也可以排定停止工作
必填的工作欄位
您在 Fleet Engine 中建立的每項工作都必須提供必要欄位,也可以提供任何選用欄位。Fleet Engine 會忽略所有其他欄位,如果工作建立要求提供已指派的 deliveryVehicleId
,就會擲回例外狀況。如要將工作指派給車輛,請使用 UpdateDeliveryVehicleRequest
。若需更多資訊,請參閲
更新工作。
欄位 | 值 |
---|---|
type |
設定為與工作類型相符的類型,可以是下列其中一項:
|
state |
State.OPEN |
task_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 |
自訂工作屬性清單。每個屬性都必須有專屬金鑰。 |
建立無法使用的工作
您可以建立一項指出無法使用的工作。例如駕駛人休息一下 如要建立無法使用的工作,請遵循下列準則:
- 將工作類型設為
UNAVAILABLE
。 - 請勿加入追蹤 ID。
- 儘管您不需要提供無法使用的任務地點, 如此便能加強整天的預計到達時間計算機制。
特殊瀏覽權限規則適用於位於車輛所在位置的車輛位置
UNAVAILABLE
項旅程分享工作。
- 與「Shipment Tracking」程式庫整合的消費型應用程式:當車輛執行無法提供服務的任務時,消費型應用程式的使用者將無法查看車輛位置,但仍可查看運送作業的狀態資訊。
- 與車隊追蹤程式庫整合的車隊追蹤應用程式:當車輛執行無法提供服務的任務時,使用車隊追蹤應用程式的車隊經理就能查看車輛位置,以便安排無法提供服務的任務。
以下範例說明如何使用 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.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.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。
要求標頭必須包含 Authorization 欄位,當中須有相應的值 不記名 <token>,其中 <token> 是由您的伺服器核發 服務帳戶角色中所述的指南,以及 JSON Web 權杖。
要求主體必須包含含有適當欄位的 Task
實體
如「非駕駛工作的工作欄位」一文所述。
curl
指令範例:
# Set $JWT, $PROJECT_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": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
建立停止工作排程
您可以為排定的停靠點建立工作;例如非駕駛任務 抵達顧客所在地點、拒絕停靠站,或是司機接到送貨時 。建立排定的停止工作時,請使用 下列規範:
- 將工作類型設為
- 請勿加入追蹤 ID。
- 您可以選擇提供位置。
以下範例說明如何透過
Java gRPC 程式庫,以及如何提出 HTTP REST 要求
CreateTask
。
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.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(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
如要從伺服器環境建立已排定的停止工作,請建立 HTTP REST
呼叫 CreateTask
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> 是工作的專屬 ID。
要求標頭必須包含「Authorization」欄位,其值為「Bearer <token>」,其中 <token> 是由伺服器根據「服務帳戶角色」和「JSON Web 權杖」中的指南所發出。
要求主體必須包含 Task
實體:
curl
指令範例:
# Set $JWT, $PROJECT_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": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM