Este documento pressupõe que você já sabe como criar e usar tarefas. Ele fornece exemplos específicos de como configurar tarefas de remessa das seguintes maneiras:
Definir a janela de tempo de destino para uma tarefa de envio: defina o período em que a tarefa será concluída.
Personalizar a visibilidade da tarefa: personalize a visibilidade das atividades da tarefa para exibição a clientes ou operadores de frota.
Consulte Criar tarefas de envio para saber mais sobre os campos de tarefas de envio. Ao atualizar outras informações sobre tarefas existentes, também é necessário incluir o identificador relevante para a tarefa, além dos campos que você atualiza para as tarefas.
Definir a janela de tempo desejada
A janela de tempo de destino é a TimeWindow em que a tarefa precisa ser concluída. Por exemplo, se você informar uma janela de tempo de entrega aos destinatários, use a janela de tempo de destino da tarefa para capturar essa janela de tempo e gerar alertas ou para analisar o desempenho de viagens anteriores.
A janela de tempo de destino consiste em um horário de início e um horário de término e pode ser definida em qualquer tipo de tarefa. A janela de tempo de destino não afeta o comportamento de roteamento.
Os exemplos a seguir mostram como definir a janela de tempo usando a biblioteca gRPC
do Java ou como fazer uma solicitação HTTP REST para UpdateTask
. Também é possível definir esse campo no momento da criação da tarefa.
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
Para definir uma janela de tempo da tarefa usando HTTP, chame PATCH
e
use updateMask
para atualizar o parâmetro targetTimeWindow
:
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow
Aqui, <id> é um identificador exclusivo para a 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 e tokens JSON da 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
Personalizar a visibilidade da tarefa
Por padrão, o Fleet Engine oferece visibilidade às atividades de tarefas que podem ser mostradas aos clientes que recebem um envio e aos operadores de frota que rastreiam os envios. Isso inclui informações como indicar o número de paradas antes de enviar uma notificação a um cliente sobre o status de entrega do pacote. É possível personalizar essas informações por tarefa para se adequar melhor ao seu modelo de negócios.
Esta seção descreve as regras de visibilidade para objetos rastreados no mapa. Essas regras se aplicam a duas categorias de objetos:
- Visibilidade do marcador de local
- Visibilidade dos dados de tarefas para tarefas de veículos ativos, como polilinhas e ETA
Regras de visibilidade do marcador de local
O Fleet Engine mostra marcadores de local para o local de entrega do envio exibido no mapa, independentemente do estado da entrega.
Regras de visibilidade dos dados de tarefas
Esta seção descreve as regras de visibilidade padrão que se aplicam aos dados de tarefas. Só é possível personalizar tarefas de veículos ativos, o que significa que apenas tarefas de retirada e entrega podem aplicar regras de visibilidade personalizadas.
As seguintes tarefas não podem ser personalizadas:
- Paradas programadas
- Tarefas de indisponibilidade
- Tarefas de veículos inativos
Regras de visibilidade de tarefas de indisponibilidade
Por padrão, o veículo não aparece no mapa se pelo menos uma tarefa de indisponibilidade for atribuída à tarefa que está sendo rastreada. Por exemplo, se o motorista estiver fazendo uma pausa ou o veículo estiver sendo reabastecido no caminho até a remessa rastreada. O horário estimado de chegada e de conclusão da tarefa ainda estão disponíveis. Não é possível personalizar essa regra.
Visibilidade das tarefas ativas do veículo
O objeto TaskTrackingInfo
fornece vários elementos de dados que podem ser
disponibilizados usando a biblioteca Shipment Tracking. Por padrão, esses campos
são mostrados quando a tarefa é atribuída ao veículo e quando ele está
a até cinco paradas da tarefa. A visibilidade termina quando a tarefa é concluída ou
cancelada.
É possível personalizar a configuração de visibilidade para cada tarefa definindo
TaskTrackingViewConfig
em uma tarefa ao criar ou atualizar a tarefa
no Fleet Engine. Isso cria regras para que elementos de dados individuais estejam
disponíveis.
A tabela a seguir mostra os campos em que você pode aplicar regras de visibilidade.
Campos de tarefas do veículo para regras de visibilidade |
---|
|
Esta tabela mostra as opções de visibilidade disponíveis para os campos listados acima.
Opções de visibilidade |
---|
|
Regras de visibilidade da localização de veículos e polilinhas do trajeto
Para uma rota rastreada, a visibilidade das polilinhas da rota está sujeita à visibilidade do veículo. Se uma polilinha de trajeto estiver visível em um trajeto ativo em que o veículo não está visível, o local do veículo ainda poderá ser inferido pelo fim da polilinha visível. Portanto, a visibilidade da poligonal de rota precisa ser tão restritiva ou mais restritiva do que a visibilidade do veículo.
Siga estas regras para fornecer uma combinação válida de polilinhas de rota / visibilidade do local do veículo.
As polilinhas de rota e a localização do veículo especificam as mesmas opções de visibilidade
Nesse cenário, a polilinha e o local do veículo definem as mesmas opções, que incluem:
- Contagem de paradas restantes
- duração até a hora prevista de chegada
- distância restante do percurso de carro
Para obedecer às regras, o valor da visibilidade das polilinhas de rotas precisa ser menor ou igual ao valor definido para a visibilidade do veículo. Neste exemplo, o limite de paradas restantes para a poligonal é definido como 3, que é menor que o valor de 5 especificado para o veículo. Isso significa que, quando a viagem rastreada estiver a 5 paradas do local da tarefa, o veículo vai aparecer, mas a rota desse veículo só vai aparecer quando a viagem estiver a 3 paradas.
```js
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"vehicleLocationVisibility": {
"remainingStopCountThreshold": 5
},
}
```
As polilinhas de trajeto e a localização do veículo especificam as diferentes opções de visibilidade
Quando as polilinhas do trajeto e a localização do veículo têm opções de visibilidade diferentes, a localização do veículo só fica visível quando ambas as opções de visibilidade são atendidas. Novamente, a visibilidade da polilinha está sujeita às regras de visibilidade do veículo:
- Sempre visível: uma polilinha de trajeto precisa usar a opção de visibilidade sempre visível quando a localização do veículo também fornecer essa mesma opção de visibilidade sempre visível.
- Nunca visível: uma linha poligonal de trajeto precisa usar uma opção de visibilidade nunca visível quando a localização do veículo usa uma opção de visibilidade nunca visível.
Confira um exemplo:
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"vehicleLocationVisibility": {
"remainingDrivingDistanceMetersThreshold": 3000
},
}
Neste exemplo, a localização do veículo só fica visível se a contagem de paradas restantes for pelo menos 3 E a distância de percurso restante for pelo menos 3.000 metros.
Exemplo de personalização da visibilidade da tarefa
Os exemplos a seguir mostram como definir uma tarefa com as seguintes regras de visibilidade:
- Mostre as polilinhas da rota se o veículo estiver a até três paradas.
- Mostre o ETA se a distância restante for menor que 5.000 metros.
- Nunca mostre a contagem de paradas restante.
- Todos os outros campos mantêm a visibilidade padrão de serem mostrados quando o veículo está a cinco paradas da tarefa.
Consulte TaskTrackingViewConfig
para gRPC ou 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
Para definir a janela de configuração da visualização de rastreamento de tarefas usando HTTP, chame PATCH
e
use updateMask
para atualizar o parâmetro taskTrackingViewConfig
:
PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig
Exemplo:
# 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