本文档假定您了解如何创建和使用任务。它提供了有关如何通过以下方式配置配送任务的具体示例：
为配送任务设置目标时间范围：设置完成任务的时间范围。
自定义任务公开范围：自定义任务活动的公开范围，以便向客户或车队运营商显示。
如需详细了解配送任务的字段，请参阅创建配送任务。 更新现有任务的其他信息时，除了更新任务的字段外，还必须包含任务的相关标识符。
设置目标时间窗口
目标时间窗口是应完成任务的 TimeWindow。例如，如果您向配送接收方传达了送货时长范围，则可以使用任务目标时间范围来捕获此时间范围并生成提醒，也可以使用此时间范围来分析过去的行程表现。
目标时间窗口由开始时间和结束时间组成，可以针对任何任务类型进行设置。目标时间窗口不会影响路由行为。
以下示例展示了如何使用 Java gRPC 库设置时间窗口，或如何向 UpdateTask 发出 HTTP REST 请求。您也可以在创建任务时设置此字段。
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)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.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
如需使用 HTTP 设置任务时间窗口，请调用 PATCH 并使用 updateMask 更新 targetTimeWindow 参数：
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow
其中 <id> 是任务的唯一标识符。请求标头必须包含值为 Bearer <token> 的 Authorization 字段，其中 <token> 由您的服务器根据服务账号角色和 JSON Web 令牌中所述的准则颁发。
# 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=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM自定义任务公开范围
默认情况下，Fleet Engine 会提供对任务活动的公开度，然后这些活动可以向接收配送的客户和跟踪配送的车队运营商显示。这包括在向客户发送包裹递送状态通知之前，指明还有多少站。您可以根据每项任务自定义此信息，以更好地适应您的业务模式。
本部分介绍了地图上跟踪对象的可见性规则。 这些规则适用于两类对象：
- 位置标记可见性
- 活跃车辆任务的任务数据可见性，例如多段线和预计到达时间
位置标记可见性规则
无论配送状态如何，Fleet Engine 都会显示地图上显示的配送地点的位置标记。
任务数据公开范围规则
本部分介绍了适用于任务数据的默认公开范围规则。 您只能自定义活跃车辆任务，这意味着只有接送任务可以应用自定义公开范围规则。
以下任务可能无法自定义：
- 计划性停止
- 不可用任务
- 非活跃车辆任务
不可用任务公开范围规则
默认情况下，如果至少有一项不可用任务分配给正在跟踪的任务，则车辆不会显示在地图上。例如，如果司机在前往被跟踪货件的途中休息或车辆正在加油。预计到达时间和预计任务完成时间仍然可用。同样，您不得自定义此规则。
有效车辆任务可见性
TaskTrackingInfo 对象提供了许多数据元素，您可以使用 Shipment Tracking Library 将这些元素显示出来。默认情况下，当任务分配给车辆且车辆距离任务地点不超过 5 站时，这些字段会显示。当任务完成或取消时，可见性结束。
您可以在 Fleet Engine 中创建或更新任务时，通过在任务上设置 TaskTrackingViewConfig，按任务自定义公开范围配置。这会创建规则，以便各个数据元素可用。
下表显示了您可以应用公开范围规则的字段。
| 可见性规则的车辆任务字段 |
|---|
|
下表显示了上述字段可用的公开范围选项。
| 公开范围选项 |
|---|
|
路线多段线和车辆位置信息公开范围规则
对于跟踪的路线，路线多段线的可见性取决于车辆的可见性。如果路线多段线在车辆不可见的有效路线上可见，则仍可通过可见多段线的末端推断车辆位置。因此，路线多段线的公开范围必须与车辆公开范围一样严格或更严格。
请遵循以下规则，提供有效的路线多段线/车辆位置信息公开范围组合。
路线多段线和车辆位置指定相同的公开范围选项
在此场景中，多段线和车辆位置都设置了相同的选项，其中包括：
- 剩余经停次数
- 距离预计到达时间还有多久
- 剩余行驶距离
为遵守这些规则，路线多段线可见性的值必须小于或等于为车辆可见性设置的值。在此示例中，多段线的剩余停靠点阈值设置为 3，小于为车辆指定的 5。这意味着，当跟踪的行程距离任务地点还有 5 站时，车辆会显示，但该车辆的路线直到行程距离任务地点还有 3 站时才会显示。
```js
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"vehicleLocationVisibility": {
"remainingStopCountThreshold": 5
},
}
```
路线多段线和车辆位置指定不同的公开范围选项
如果路线多段线和车辆位置具有不同的公开范围选项，则只有在同时满足两者的公开范围选项时，车辆位置才可见。同样，多段线的公开范围取决于车辆的公开范围规则：
- 始终可见：如果车辆位置也提供始终可见选项，则路线多段线必须使用始终可见选项。
- 永不可见：如果车辆位置使用永不可见可见性选项，则路线多段线必须使用永不可见可见性选项。
示例如下：
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"vehicleLocationVisibility": {
"remainingDrivingDistanceMetersThreshold": 3000
},
}
在此示例中，仅当剩余停靠点数至少为 3 且剩余行驶距离至少为 3, 000 米时，车辆位置才可见。
任务公开范围自定义示例
以下示例展示了如何设置具有以下公开范围规则的任务：
- 如果车辆距离站点不超过 3 站，则显示路线多段线。
- 如果剩余行驶距离小于 5,000 米，则显示预计到达时间。
- 一律不显示剩余停靠点数量。
- 其他每个字段都会保留默认显示设置，即在车辆距离任务地点不超过 5 站时显示。
请参阅 TaskTrackingViewConfig，了解 gRPC 或 REST。
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)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.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
如需使用 HTTP 设置任务跟踪器视图配置窗口，请调用 PATCH 并使用 updateMask 更新 taskTrackingViewConfig 参数：
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig
例如：
# 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=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM