本文档假定您已阅读舰队引擎简介部分中有关预定任务的入门指南,以及本部分中的什么是预定任务?。
适用于预定任务的 Fleet Engine 提供以下不同的大类任务:
- 送货任务:用于驾驶任务,包括取货和送货。
- 不可用任务:用于司机不可用的时间,例如强制休息时间。
- 预定停靠点任务:用于在投递箱或客户地点执行非驾驶任务,例如进入建筑物或找到送货点所需的时间。
本文档介绍了如何在服务器上创建非货运任务。对于配送任务类型,请参阅创建配送任务。
非驾驶任务的任务字段
本部分介绍了不可用任务和预定停止任务所需的任务字段。
必需的任务字段
对于您在 Fleet Engine 中创建的每个任务,您都必须为其提供必需字段,也可以提供任何可选字段。Fleet Engine 会忽略所有其他字段,如果任务创建请求提供已分配的 deliveryVehicleId
,则会抛出异常。如需将任务分配给车辆,请使用 UpdateDeliveryVehicleRequest
。如需了解详情,请参阅更新任务。
字段 | 值 |
---|---|
type |
设置为与任务类型匹配的类型,即以下类型之一:
|
state |
State.OPEN |
task_id |
唯一任务 ID。不得是相应货件的跟踪编号。如果您的系统中没有任务 ID,您可以生成一个通用唯一标识符 (UUID)。如需了解详情,请参阅任务 ID。 |
tracking_id |
仅限 PICKUP 或 DELIVERY 任务:您用于跟踪货件的编号或标识符。请勿为非货件任务提供此字段。 |
planned_location |
仅限 PICKUP 、DELIVERY 或 SCHEDULED_STOP 任务:要完成任务的位置。对于 UNAVAILABLE 任务,此权限不是必需的。 |
task_duration |
完成任务所需的预计额外时间。例如,寻找停车位或步行前往交接地点。 |
可选的货件任务字段
字段 | 值 |
---|---|
target_time_window |
任务应完成的时间窗口。此字段不会影响路由行为。 |
task_tracking_view_config |
仅限 PICKUP 或 DELIVERY 任务:任务跟踪的配置,用于指定在哪些情况下最终用户可以查看哪些数据元素。 |
attributes |
自定义任务属性的列表。每个属性都必须具有唯一的键。 |
创建不可用性任务
您可以创建表示不可用的任务,例如表示司机休息。如需创建不可用时段任务,请遵循以下准则:
- 将任务类型设置为
UNAVAILABLE
。 - 不包含跟踪 ID。
- 虽然您不必为不可用任务提供位置信息,但这样做有助于系统在一天内更准确地计算预计到达时间。
当车辆处于UNAVAILABLE
任务中以进行行程分享时,车辆位置会受到特殊可见性规则的约束。
- 与 Shipment Tracking 库集成的消费者应用:当车辆处于不可用任务状态时,消费者应用的用户无法看到车辆位置,但仍可看到货件的状态信息。
- 与 Fleet Tracking 库集成的车队跟踪应用:当车辆处于不可用任务中时,使用车队跟踪应用的车队经理将能够看到不可用任务的车辆位置。
以下示例展示了如何使用 Java gRPC 库创建安排的不可用任务,以及如何向 CreateTask
发出 HTTP REST 请求。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
```
REST
如需从服务器环境中创建不可用任务,请向 CreateTask
发出 HTTP REST 调用:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> 是任务的唯一标识符。
请求标头必须包含一个 Authorization 字段,其值为 Bearer <token>,其中 <token> 是由您的服务器根据服务账号角色和 JSON Web 令牌中所述的准则颁发的。
请求正文必须包含一个 Task
实体,其中包含非驾驶任务的任务字段中所述的相应字段。
示例 curl
命令:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
创建预定停止任务
您可以为预定停靠点创建任务;例如,在客户所在地执行非驾驶任务、加油停靠或驾驶员从接驳车辆接收货物时。创建预定停止任务时,请遵循以下准则:
- 将任务类型设置为
- 不包含跟踪 ID。
- 您可以选择性地提供位置信息。
以下示例展示了如何使用 Java gRPC 库创建安排的不可用任务,以及如何向 CreateTask
发出 HTTP REST 请求。
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
```
REST
如需从服务器环境中创建预定停止任务,请向 CreateTask
发出 HTTP REST 调用:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>
<id> 是任务的唯一标识符。
请求标头必须包含一个 Authorization 字段,其值为 Bearer <token>,其中 <token> 是由您的服务器根据服务账号角色和 JSON Web 令牌中所述的准则颁发的。
请求正文必须包含 Task
实体:
示例 curl
命令:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM