此页面由 Cloud Translation API 翻译。

配置任务

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

为发货任务设置目标时间范围：设置任务完成的时间范围。
自定义任务可见性：自定义任务活动的可见性，以向客户或车队运营商显示。

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

设置目标时间范围

目标时间范围是指任务应完成的 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 会提供对任务活动的直观了解，这些活动随后可向接收运输的客户和跟踪运输的车队运营商显示。这包括指明在向客户发送包裹递送状态通知之前需要经过多少个经停点等信息。您可以按任务自定义此信息，以更好地适应您的业务模式。

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

地点标记的公开范围
有效车辆任务（例如多段线和预计到达时间）的任务数据可见性

地点标记可见性规则

无论配送状态如何，车队引擎都会在地图上显示配送地址的位置标记。

任务数据公开范围规则

本部分介绍了适用于任务数据的默认公开范围规则。您只能自定义正在进行的车辆任务，这意味着只有上车点和下车点任务可以应用自定义的公开范围规则。

以下任务无法自定义：

计划性停止
不可用性任务
无效的车辆任务

不可用任务的公开范围规则

默认情况下，如果正在跟踪的任务至少分配了一个“不具备空闲状态”任务，车辆将不会显示在地图上。例如，如果司机在运送被跟踪的运输包裹的途中休息或加油。预计到达时间和预计任务完成时间仍可用。再次提醒，您无法自定义此规则。

有效车辆任务的公开范围

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 个经停点以内，则显示路线多段线。
如果剩余的驾车距离短于 5000 米，则显示预计到达时间。
切勿显示剩余经停点数。
所有其他字段均保留默认的可见性，即在车辆距离任务 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

配置任务

设置目标时间范围

gRPC

REST

自定义任务的公开范围

地点标记可见性规则

任务数据公开范围规则

不可用任务的公开范围规则

有效车辆任务的公开范围

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

路线多段线和车辆位置指定了相同的公开范围选项

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

任务公开范围自定义示例

gRPC

REST

后续步骤