本文件假設您熟悉下列項目:
如車隊引擎 Essentials 中的「排定工作」所述,您可以建立工作並將其與車輛停靠站建立關聯,以模擬工作與車輛預期停靠位置之間的實際關聯,讓駕駛員能夠完成工作。
您可以在這裡管理任務在生命週期的進度 並向 Fleet Engine 傳送更新,讓 Fleet Engine 以最佳方式執行轉送和狀態 並在工作歷程中持續更新其中一個重要方法,就是在車輛接近、抵達和離開停靠站時更新車輛停靠站。如此一來,您就能透過報告和分析 機群運算子和使用者。這些狀態更新如下:
- En route:
VehicleStop
的STATE
列舉使用ENROUTE
可 表示停靠站位於車輛行程清單的下一站。 從工作的角度而言,這代表所有與停靠站相關的工作 下一個問題仍未解決 - 已抵達:
VehicleStop
的STATE
列舉使用ARRIVED
表示 車輛已抵達停靠站。從工作的角度來看 表示與停止作業相關聯的任何任務 - 已完成:您可以將停靠站從車輛的停靠站清單中移除,以標示停靠站已完成。這樣一來,Fleet Engine 就會自動將所有相關聯的工作標示為「已關閉」。如要進一步瞭解如何關閉工作,請參閱「完成工作」。
本文件說明如何使用伺服器端做法更新停止狀態。如果您讓駕駛員能夠使用可信任的裝置管理工作,也可以透過駕駛員應用程式執行這項操作。請只使用一種方法,以免發生競速 並維護單一資料來源。
車輛正在前往停靠站
車輛開始前往下一個停靠站時,系統應通知 Fleet Engine。這有助於改善預計到達時間和路線計算結果。
停止更新功能的必填欄位
Fleet Engine 會忽略通知實體中其他所有欄位。
欄位 | 值 |
---|---|
remainingVehicleJourneySegments
|
剩餘車輛停靠站清單,狀態標示為 State.NEW。 |
導向停靠站範例
以下範例說明如何通知 Fleet Engine 車輛
使用 Java gRPC 程式庫或 HTTP
對 UpdateDeliveryVehicle
發出的 REST 呼叫。所有其他停靠站都會標示為新的。
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 欄位,當中須有相應的值 不記名 <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。 |
抵達停靠站的例子
以下範例說明如何在車輛抵達時通知 Fleet Engine
方法是使用 Java gRPC 程式庫或 HTTP REST 呼叫,
UpdateDeliveryVehicle
。所有其他停靠站都會標示為新站。
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 欄位,當中須有相應的值 不記名 <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 欄位,當中須有相應的值 不記名 <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