本文档假定您了解如何创建和使用任务。其中提供了有关如何以以下方式配置配送任务的具体示例：
为配送任务设置目标时间范围：设置完成任务的时间范围。
自定义任务可见性：自定义任务活动的可见性，以便向客户或车队运营方显示。
如需详细了解货件任务的字段，请参阅创建货件任务。 更新现有任务的其他信息时，除了要更新的任务字段之外，您还必须包含任务的相关标识符。
设置目标时间窗口
目标时间窗口是指任务应完成的 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 网络令牌中所述的准则签发的。
# 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 对象提供了一些数据元素，您可以使用货件跟踪库来显示这些元素。默认情况下，当任务分配给车辆时，以及当车辆距离任务不超过 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 个停靠站以内时显示。
如需了解 gRPC 或 REST，请参阅 TaskTrackingViewConfig。
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