此页面由 Cloud Translation API 翻译。

配置任务

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

为配送任务设置目标时间范围：设置时间范围以完成任务
自定义任务可见性：自定义任务 activity 的可见性显示给客户或舰队运营商。

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

设置目标时间范围

目标时间范围是指任务应完成的 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 提供了任务 activity 的可见性，向接收货物的客户和车队运营人员显示货运跟踪。这包括在向客户发送包裹送达通知之前停止状态。您可以根据每项任务自定义此信息，以便更好地满足业务模式

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

位置标记的可见性
有效车辆任务（例如多段线和预计到达时间）的任务数据可见性

地点标记可见性规则

Fleet Engine 显示运单送货地点的位置标记（不管投放状态如何），都会在地图上显示。

任务数据可见性规则

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

以下任务无法自定义：

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

不可用任务可见性规则

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

活跃车辆任务可见性

TaskTrackingInfo 对象提供了许多数据元素，可以使用物流跟踪库默认情况下，这些字段任务分配给车辆时以及车辆 5 个站内。任务完成或取消后，公开范围将结束。

您可以通过设置创建或更新任务时，针对该任务的 TaskTrackingViewConfig Fleet Engine 中。这样可为各个数据元素创建规则，可用。

下表显示了您可以对哪些字段应用公开范围规则。

可见性规则的车辆任务字段
路线多段线预计到达时间预计任务完成时间到任务的剩余驾车距离剩余经停点数车辆位置信息

下表显示了上述字段可用的公开范围选项。

公开范围选项
剩余经停点数预计到达时间前的时长剩余行驶距离始终显示永不显示

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

对于跟踪的路线，路线多段线的可见性取决于车辆的可见性。如果车辆未显示在某条有效路线上，但该路线上显示了路线多段线，则仍可根据可见多段线的终点推断出车辆位置。因此，路线多段线的可见性必须与车辆可见性一样严格或更严格。

请遵循以下规则，提供有效的路线多段线/车辆位置可见性组合。

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

在此场景中，多段线和车辆位置都设置了相同的选项，包括：

剩余经停点数
预计到达时间后
剩余可行驶距离

为遵守规则，路线多段线的可见性值必须小于大于或等于为车辆可见性设置的值。在此示例中多段线的剩余停靠点阈值设为 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

后续步骤