Este documento pressupõe que você leu o guia introdutório sobre [Tarefas programadas][1] na seção Introdução ao Fleet Engine, bem como [O que é uma tarefa programada?][2] nesta seção.
O Fleet Engine para tarefas programadas oferece diferentes categorias de tarefas:
- Tarefas de transporte: use para tarefas de direção, incluindo retirada e entrega de remessas.
- Tarefas de indisponibilidade: use para momentos em que os motoristas não estão disponíveis, como em intervalos obrigatórios.
- Tarefas de parada programada: use para tarefas que não envolvem dirigir em caixas de coleta ou locais de clientes, como o tempo para entrar em um prédio ou localizar um ponto de entrega.
Este documento aborda como criar tarefas de envio no seu servidor. Para outros tipos de tarefa, consulte Criar outros tipos de tarefa.
Campos de tarefa de transporte
Esta seção documenta os campos necessários para tarefas de retirada e entrega.
Campos de tarefa obrigatórios
Para cada tarefa criada no Fleet Engine, é necessário preencher os campos obrigatórios
e, se quiser, os campos opcionais. O Fleet Engine
ignora todos os outros campos e gera uma exceção se uma solicitação de criação de tarefa
fornecer um deliveryVehicleId atribuído. Para atribuir tarefas a um veículo,
use UpdateDeliveryVehicleRequest. Para mais informações, consulte
Atualizar tarefas.
| Campo | Valor |
|---|---|
type |
Defina como o tipo que corresponde ao tipo de tarefa, que é um dos seguintes:
|
state |
State.OPEN |
task_id |
ID exclusivo da tarefa. Não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefa no sistema, gere um identificador universalmente exclusivo (UUID). Para mais detalhes, consulte IDs de tarefa. |
tracking_id |
Somente tarefas de PICKUP ou DELIVERY:
o número ou identificador que você está usando para rastrear uma remessa. Não
forneça esse campo para tarefas que não sejam de remessa. |
planned_location |
Somente tarefas PICKUP, DELIVERY ou
SCHEDULED_STOP: o
local em que a tarefa será concluída. Não é necessário para
tarefas UNAVAILABLE. |
task_duration |
O tempo esperado para concluir a tarefa. Por exemplo, para procurar estacionamento ou caminhar até o local de entrega. |
Campos opcionais de tarefa de envio
| Campo | Valor |
|---|---|
target_time_window |
A janela de tempo em que a tarefa precisa ser concluída. Esse campo não afeta o comportamento de roteamento. |
task_tracking_view_config |
Somente tarefas PICKUP ou DELIVERY:
A configuração para o rastreamento de planilhas de controle de tarefas que especifica quais elementos de dados
ficam visíveis para os usuários finais em quais circunstâncias. |
attributes |
Uma lista de atributos de tarefa personalizados. Cada atributo precisa ter uma chave exclusiva. |
Criar uma tarefa de retirada de remessa
Para usar o Fleet Engine para acompanhar a atividade de um motorista que está retirando uma remessa,
crie uma tarefa de retirada de remessa. Isso envolve definir o atributo de tipo de tarefa como
PICKUP. O exemplo a seguir ilustra uma retirada de remessa no Grand
Indonesia East Mall.
Os exemplos a seguir mostram como criar uma tarefa de retirada de remessa usando a
[biblioteca gRPC do Java][4] ou como fazer uma solicitação HTTP REST para
[CreateTask][5].
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.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.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 a 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
Para criar uma tarefa de retirada de remessa em um ambiente de servidor, faça uma chamada HTTP REST para CreateTask:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id><id> é um identificador exclusivo da tarefa.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é emitido pelo servidor de acordo com as diretrizes descritas em [Papéis da conta de serviço][6] e [Tokens da Web JSON][7].
O corpo da solicitação precisa conter uma entidade Task com os campos apropriados descritos em [Campos de tarefa de transporte][8].
Comando curl de exemplo:
# Set $JWT, $PROJECT_ID, $TRACKING_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": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOMCriar uma tarefa de entrega de remessa
Para usar o Fleet Engine para acompanhar a atividade de um motorista que está entregando uma remessa,
crie uma tarefa de entrega de remessa. Isso envolve definir o atributo de tipo de tarefa
como DELIVERY. O exemplo a seguir ilustra uma entrega no Grand Indonesia East Mall.
Os exemplos a seguir mostram como criar uma tarefa de retirada de remessa usando a
[biblioteca gRPC do Java][4] ou como fazer uma solicitação HTTP REST para
[CreateTask][5].
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.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.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
Para criar uma tarefa de retirada de remessa em um ambiente de servidor, faça uma chamada HTTP REST para CreateTask:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id><id> é um identificador exclusivo da tarefa.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é emitido pelo servidor de acordo com as diretrizes descritas em [Papéis da conta de serviço][6] e [Tokens da Web JSON][7].
O corpo da solicitação precisa conter uma entidade Task:
Comando curl de exemplo:
# Set $JWT, $PROJECT_ID, $TRACKING_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": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
```placeidtrips1: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#locationinfo placeidtrips2: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html placeidtrips3: /maps/documentation/mobility/fleet-engine/reference/tasks/rpc/maps.fleetengine.delivery.v1.html#maps.fleetengine.delivery.v1.LocationInfo.FIELDS.string.maps.fleetengine.delivery.v1.LocationInfo.place placeidtrips4: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/LocationInfo.html#FIELDS.place
A seguir
- [Criar outros tipos de tarefa][13]
- [Atualizar tarefas][3]
[1]: /maps/documentation/mobility/fleet-engine/essentials/tasks-intro [2]: /maps/documentation/mobility/fleet-engine/journeys/tasks [3]: update-tasks [4]: /maps/documentation/mobility/fleet-engine/essentials/client-libraries-tasks#java [5]: /maps/documentation/mobility/fleet-engine/reference/tasks/rest/v1/providers.tasks/create [6]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts [7]: /maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/jwt [8]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-shipment-tasks#shipment_task_fields [13]: /maps/documentation/mobility/fleet-engine/journeys/tasks/create-other-tasks