配置任务

本文档假定您了解如何创建和使用任务。它提供了有关如何通过以下方式配置配送任务的具体示例：

为配送任务设置目标时间窗口：设置任务的完成时间窗口。
自定义任务可见性：自定义任务活动的可见性，以便向客户或车队运营方显示。

如需详细了解配送任务的字段，请参阅创建配送任务。更新现有任务的其他信息时，除了要更新的字段之外，您还必须包含任务的相关标识符。

设置目标时间窗口

目标时间窗口是指任务应在其中完成的 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> 是任务的唯一标识符。请求标头必须包含一个字段 Authorization，其值为 Bearer <token>，其中 <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 提供任务活动的可见性，然后可以向接收配送的客户和跟踪配送的车队运营方显示这些活动。这包括在向客户发送有关包裹配送状态的通知之前，指明停靠站数量等信息。您可以根据具体任务自定义此信息，以更好地适应您的业务模式。

本部分介绍了地图上跟踪对象的可见性规则。这些规则适用于两类对象：

地点标记可见性
有效车辆任务的任务数据可见性，例如多段线和预计到达时间 (ETA)

地点标记可见性规则

无论配送状态如何，Fleet Engine 都会显示地图上显示的配送地点的地点标记。

任务数据可见性规则

本部分介绍了适用于任务数据的默认可见性规则。您只能自定义 有效车辆任务，这意味着只有取货和送货任务可以应用自定义可见性规则。

以下任务可能无法自定义：

计划停靠站
不可用任务
无效车辆任务

不可用任务可见性规则

默认情况下，如果至少有一个不可用任务分配给正在跟踪的任务，则车辆不会显示在地图上。例如，如果司机在前往跟踪的配送地点的途中休息或为车辆加油。预计到达时间和预计任务完成时间仍然可用。同样，您可能无法自定义此规则。

有效车辆任务可见性

The 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 且剩余驾车距离至少为 3000 米时，车辆位置才可见。

任务可见性自定义示例

以下示例展示了如何设置具有以下可见性规则的任务：

如果车辆距离 3 个停靠站以内，则显示路线多段线。
如果剩余驾车距离小于 5000 米，则显示预计到达时间。
永不显示剩余停靠站数量。
当车辆距离任务地点 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

后续步骤

删除任务

配置任务 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

设置目标时间窗口

gRPC

REST

自定义任务可见性

地点标记可见性规则

任务数据可见性规则

不可用任务可见性规则

有效车辆任务可见性

路线多段线和车辆位置可见性规则

路线多段线和车辆位置指定相同 的可见性选项

路线多段线和车辆位置指定不同 的可见性选项

任务可见性自定义示例

gRPC

REST

后续步骤

配置任务

路线多段线和车辆位置指定相同的可见性选项

路线多段线和车辆位置指定不同的可见性选项