本文件假設您熟悉下列項目：
如車隊引擎 Essentials 中的「排定工作」所述，您可以建立工作並將其與車輛停靠站建立關聯，以模擬工作與車輛預期停靠位置之間的實際關聯，讓駕駛員能夠完成工作。
接著，您可以傳送更新至 Fleet Engine，藉此管理任務在整個生命週期中的進度，讓 Fleet Engine 在任務流程中盡可能執行路徑和狀態更新。其中一個重要方法，就是在車輛靠近、抵達和離開停靠站時更新車輛停靠站。這可讓車隊營運人員和使用者回報及分析任務進度。這些狀態更新如下：
- 行程中：
VehicleStop的STATE列舉使用ENROUTE表示停靠站是車輛行程清單中的下一個停靠站。從工作角度來看，這表示與停靠點相關聯的任何工作，都是清單上下一個要完成的工作。 - Arrived：
VehicleStop的STATE列舉使用ARRIVED表示車輛已抵達停靠站。從工作角度來看，這表示與停靠站相關的任何工作都會處於運作狀態。 - 已完成：您可以將站點從車輛的站點清單中移除，藉此標示該站點已完成。這麼做時，Fleet Engine 會自動將所有相關聯的工作標示為「已關閉」。如要進一步瞭解如何關閉工作，請參閱「完成工作」。
本文件說明如何使用伺服器端方法更新停止狀態。如果您讓駕駛員能夠使用可信任的裝置管理工作，也可以透過駕駛員應用程式執行這項操作。請只使用一種方法，以免發生競爭狀況，並維持單一可靠來源。
車輛正在前往停靠站的途中
車輛開始前往下一個停靠站時，系統應通知 Fleet Engine。這有助於改善預估抵達時間和路線計算結果。
停止更新的必填欄位
Fleet Engine 會忽略通知中的所有其他欄位。
| 欄位 | 值 |
|---|---|
remainingVehicleJourneySegments
|
剩餘車輛停靠站清單，狀態標示為 State.NEW。 |
前往停靠站的路線示例
以下範例說明如何使用 Java gRPC 程式庫或對 UpdateDeliveryVehicle 的 HTTP REST 呼叫，通知 Fleet Engine 車輛正在前往下一站的途中。所有其他站都會標示為新站。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
- <id> 是工作專屬 ID。
- 要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中 <token> 是由伺服器根據「服務帳戶角色」和「JSON Web 權杖」中的指南所發出。
- 要求主體必須包含
DeliveryVehicle實體：
curl 指令範例：
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
車輛抵達停靠站
車輛抵達停靠站時，Fleet Engine 必須收到通知。
停止更新的必填欄位
Fleet Engine 會忽略通知中的所有其他欄位。
| 欄位 | 值 |
|---|---|
remainingVehicleJourneySegments
|
剩餘車輛停靠站清單，狀態標示為 State.NEW。 |
抵達停靠站範例
以下範例說明如何使用 Java gRPC 程式庫或對 UpdateDeliveryVehicle 發出 HTTP REST 呼叫，通知 Fleet Engine 車輛已抵達停靠站。所有其他停靠站都會標示為新站。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
- <id> 是工作專屬 ID。
- 要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中 <token> 是由伺服器根據「服務帳戶角色」和「JSON Web 權杖」中的指南所發出。
- 要求主體必須包含
DeliveryVehicle實體：
curl 指令範例：
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
車輛完成停靠
車輛完成停靠後，Fleet Engine 必須收到通知。這會導致與停靠站相關聯的所有工作都設為已關閉狀態。
停止更新的必填欄位
Fleet Engine 會忽略通知中的所有其他欄位。
| 欄位 | 值 |
|---|---|
remainingVehicleJourneySegments |
剩餘車輛停靠站清單，狀態標示為 State.NEW。清單中的第一個停靠站的狀態必須標示為 State.ENROUTE。 |
完成停用範例
以下範例說明如何使用 Java gRPC 程式庫或對 UpdateDeliveryVehicle 發出 HTTP REST 呼叫，通知 Fleet Engine 車輛已抵達停靠站。所有其他停靠站都會標示為新站。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} 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>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
- <id> 是工作專屬 ID。
- 要求標頭必須包含「Authorization」欄位，其值為「Bearer <token>」，其中 <token> 是由伺服器根據「服務帳戶角色」和「JSON Web 權杖」中的指南所發出。
- 要求主體必須包含
DeliveryVehicle實體：
curl 指令範例：
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM