Modele as atividades da sua frota na primeira e última milha de entregas com a API Fleet Engine Deliveries. Você pode usar essa API com o SDK do Driver para Android e iOS, ou diretamente usando chamadas HTTP REST ou gRPC.
Configuração inicial
Configure a API Fleet Engine Deliveries no Console do Google Cloud.
Para informações sobre as etapas a serem seguidas no console e como criar JSON Web Token para autorização, consulte Autenticação e autorização.
Para mais detalhes sobre como usar o console, consulte a Documentação do console do Google Cloud.
Verificar sua configuração
Depois de criar as contas de serviço, verifique se a configuração foi concluída e criar um veículo de entrega. Verificando sua configuração imediatamente garante a solução de problemas de autorização comuns que podem surgir configurando seu projeto. Há duas maneiras de verificar a configuração:
Teste duas partes principais da sua configuração: assinatura do token de autorização e envio da avaliação criação de veículos com o Utilitário de linha de comando
gcloud
. Para detalhes, consulte a seção Como verificar sua configuração guia.Teste sua configuração com o Scripts de amostra de autenticação do Fleet Engine.
Bibliotecas de cliente
Para uma melhor experiência de desenvolvedor com gRPC ou REST bruto, use o em várias linguagens de programação comuns. Para instruções sobre como obter bibliotecas de clientes para seu aplicativo de servidor, consulte Bibliotecas de cliente.
Os exemplos de Java nesta documentação pressupõem que você esteja familiarizado com gRPC.
Estruturas de dados
A API Fleet Engine Deliveries usa duas estruturas de dados para modelar a coleta e a entrega de fretes:
- O veículo de entrega usado para transportar a remessa.
- As tarefas de retirada e entrega de remessas.
Você também usa tarefas para modelar as pausas para motoristas e paradas programadas ao longo do dia.
Veículos de entrega
Os veículos de entrega transportam remessas de um depósito para um local de entrega, e de um local de coleta para o depósito. Em certos casos, eles também podem transportar uma remessa diretamente do local de retirada para o local de entrega.
Usar o SDK do Driver para criar um objeto DeliveryVehicle
no Fleet Engine
e enviar atualizações de localização para rastreamento de remessas e frotas.
DeliveryVehicle
objetos.
Tarefas
Para as ações que um veículo realiza durante o dia, você atribui tarefas de acordo com o tipo de ação:
- Para retiradas e entregas, atribua Tarefas de envio.
- Quando os motoristas não estão disponíveis, como pausas obrigatórias, atribuir Tarefas de indisponibilidade.
- Para tarefas que não são como motorista em caixas de depósito ou em locais de clientes, atribua Tarefas com paradas programadas.
Cada tarefa atribuída precisa ter um ID exclusivo, mas as tarefas podem ter o mesmo ID de acompanhamento. Quando a Fleet Engine calcula o HEC para cada tarefa, ele usa todas as tarefas e a ordem em que eles são programados para fazer estimativas. Para mais informações sobre IDs de tarefas, consulte Diretrizes de ID de tarefas.
Para criar tarefas no Fleet Engine, use o gerenciador de tarefas do SDK do Driver.
Tarefas de envio
Criar tarefas de remessa para retirada e entrega de uma remessa e inclua as seguintes informações:
- O local da retirada ou entrega.
- Um número ou ID de rastreamento.
- Um tempo de espera para contabilizar um tempo adicional para concluir a tarefa; procure para estacionar ou caminhar até o local de transferência.
- Um ID de tarefa exclusivo. Consulte as diretrizes de IDs de tarefas.
Para mais informações, consulte os tópicos a seguir:
Android
iOS
Tarefas de indisponibilidade
As tarefas de indisponibilidade abrangem períodos em que um veículo não está disponível retiradas ou entregas, como intervalos para reabastecer o veículo ou motorista intervalos de descanso.
Crie uma tarefa de indisponibilidade com as seguintes informações:
- A duração do intervalo.
- Opcionalmente, o local da pausa. Você não precisa fornecer um local específico, mas isso proporciona janelas de HEC mais precisas ao longo do dia.
Para mais informações, consulte os tópicos a seguir:
Android
iOS
Tarefas com paradas programadas
Criar tarefas de paradas programadas para determinar as paradas necessárias para um veículo de entrega fazer. Por exemplo, crie uma tarefa de parada programada para um horário programado parada de coleta em um local específico, independentemente de outras entregas ou retiradas no mesmo local. Também é possível criar tarefas com paradas programadas para coletas de caixas de depósito ou transferências de modelos alimentadores e veículos ou paradas em centros e pontos de serviço.
Para mais informações, consulte os tópicos a seguir:
Android
iOS
Diretrizes do ID da tarefa
Ao criar IDs de tarefas, siga estas diretrizes de conteúdo e formato:
- Criar IDs de tarefas exclusivos
- Não exponha informações de identificação pessoal (PII) ou dados de texto limpos.
- Use strings Unicode válidas.
- Use até 64 caracteres.
- Não inclua os seguintes caracteres ASCII: "/", ":", "\", "?" ou "#".
- Normalize de acordo com o Formulário C de normalização Unicode.
Confira abaixo alguns exemplos de IDs de tarefas adequados:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
A tabela a seguir mostra exemplos de IDs de tarefas sem suporte:
IDs de tarefas sem suporte | Motivo |
---|---|
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Violar as PII e os requisitos de caracteres: vírgulas, pontos, dois-pontos e barras. |
JohnDoe-577b484da26f-Cupertino-SantaCruz | Viola os requisitos de PII. |
4R0oXLToF"112 Dr. East Hartford, CT06118"577b484da26f8a | Violar os requisitos de PII e caracteres: espaços em branco, vírgulas e aspas. Com mais de 64 caracteres. |
Mais recursos
Para ver os campos específicos contidos em cada dado
consulte a documentação de referência da API para DeliveryVehicle
(gRPC, REST)
e Task
(gRPC, REST).
Vida útil de um veículo
O objeto DeliveryVehicle
representa um veículo de entrega de primeira ou última milha.
Crie um objeto DeliveryVehicle
usando:
- O ID do projeto do Google Cloud que contém a conta de serviço usada para chamar as APIs do Fleet Engine.
- ID do veículo do cliente
Use documentos de identificação exclusivos para cada veículo. Não reutilize um ID de veículo a menos que não haja tarefas ativas para o veículo original.
O Fleet Engine exclui automaticamente DeliveryVehicle
objetos que não foram
foi atualizado usando UpdateDeliveryVehicle
após sete dias. As recomendações
para manter um veículo disponível no Fleet Engine é atualizar a localização dele
em intervalos regulares. Atualizações para a maioria dos outros campos no DeliveryVehicle
entidade também vai prolongar a vida útil, desde que o novo valor do campo seja diferente
do que já existe.
Para saber se um veículo existe:
- Faça uma chamada para
UpdateDeliveryVehicle
. - Se você receber um erro NOT_FOUND, chame
CreateDeliveryVehicle
. para recriar o veículo. Se a chamada retornar um veículo, ele ainda estará disponível para atualização.
Atributos do veículo
A entidade DeliveryVehicle
contém um campo repetido de
DeliveryVehicleAttribute
. A API ListDeliveryVehicles
inclui um filter
que pode limitar as entidades DeliveryVehicle
retornadas àquelas com a
atributos especificados. O DeliveryVehicleAttribute
não afeta o Fleet Engine
de roteamento.
Não inclua informações de identificação pessoal (PII) ou informações sensíveis em atributos, já que esse campo pode ficar visível para os usuários.
A vida de uma tarefa
É possível criar, atualizar e consultar tarefas no Fleet Engine com as interfaces gRPC ou REST da API Deliveries.
Um objeto Task
tem um campo de estado para acompanhar a progressão
o ciclo de vida dele. Os valores se movem de OPEN para CLOSED. Novas tarefas são criadas
no estado OPEN, o que indica que:
- A tarefa ainda não foi atribuída a um veículo de entrega.
- O veículo de entrega ainda não passou da parada de veículo atribuída à tarefa.
Diretrizes de tarefas
Só é possível atribuir uma tarefa a um veículo quando ele está no estado ABERTO.
Para cancelar uma tarefa, remova-a da lista de paradas de veículos, o que define o estado da tarefa para CLOSED automaticamente.
Quando o veículo da tarefa parar o veículo:
Atualize o campo de resultado da tarefa para SUCCEEDED ou FAILED.
Especifique o carimbo de data/hora do evento.
A biblioteca JavaScript Fleet Tracking indica o resultado da tarefa e, o status da tarefa será definido automaticamente como FECHADA. Para mais informações, consulte Rastreie sua frota com a biblioteca JavaScript Fleet Tracking.
Assim como os veículos, o Fleet Engine exclui as tarefas que não foram atualizadas após sete dias e, se tentar criar uma tarefa com um ID que já existe, ela retornará um erro.
Observação:o Fleet Engine não dá suporte à exclusão explícita de uma tarefa. O serviço exclui automaticamente as tarefas após sete dias sem atualizações. Se você quiser reter dados de tarefas por mais de sete dias, você deve implementar essa capacidade por conta própria.
Atributos da tarefa
A entidade Task
contém um campo repetido de
TaskAttribute
, que pode ter um valor de um dos três tipos: string, número
e booleano. A API ListTasks
inclui um campo filter
que pode limitar os valores
Task
às entidades com os atributos especificados. Os atributos da tarefa não
afetar o comportamento de roteamento do Fleet Engine.
Não inclua informações de identificação pessoal (PII) ou outros dados sensíveis informações nos atributos, já que esses atributos podem ser visíveis aos usuários.
Gerencie o ciclo de vida do veículo e da tarefa
Lembrete: seu sistema interno atua como a fonte confiável dos dados que o A API Fleet Engine Deliveries é aumentada por você.
Para gerenciar ciclos de vida de veículos e tarefas no sistema, use a API Fleet Engine Deliveries para criar, atualizar e rastrear seus veículos e as tarefas associadas a eles.
Ao mesmo tempo, o aplicativo do motorista se comunica diretamente com o Fleet Engine para atualizar as informações de local e trajeto do dispositivo. Com esse modelo, o Fleet Engine gerenciar a localização em tempo real com eficiência. Ele envia a localização diretamente para o biblioteca de acompanhamento, que pode ser usada para atualizar os consumidores sobre o status do pedido.
Por exemplo, suponha que você tenha o seguinte cenário:
- Um motorista se aproximando de uma parada de entrega. O aplicativo do motorista envia a localização para Fleet Engine.
- O Fleet Engine envia a localização do dispositivo ao biblioteca de acompanhamento do cliente, que seu aplicativo para consumidor usa para alertar o cliente à proximidade do pacote.
- Depois que o motorista conclui o envio, ele clica no botão "Envio entregue" no aplicativo do driver.
- A mensagem "Envio entregue" envia as informações ao sistema de back-end, que executa as etapas necessárias de validação e verificação da empresa.
- Seu sistema confirma a tarefa como CONCLUÍDA e atualiza o Fleet Engine usando o API Deliveries.
O diagrama a seguir ilustra esses processos em um nível genérico. Ela também mostra a relação padrão entre seu sistema, o cliente e Fleet Engine.
Gerenciar tokens do cliente
Atualizações de localização originadas do aplicativo do motorista e enviadas diretamente ao Fleet Engine exigem tokens de autorização. Esta é a abordagem recomendada para gerenciar as atualizações do cliente no Fleet Engine:
Gere o token usando o usuário de driver não confiável da entrega do Fleet Engine o papel da conta de serviço.
Fornecer um token de escopo limitado ao aplicativo do driver. Este escopo só permite atualizar o local do dispositivo no Fleet Engine.
Com essa abordagem, as chamadas provenientes de dispositivos móveis ambientes de baixa confiança, siga as princípio de privilégio mínimo.
Outros papéis da conta de serviço
Se, em vez disso, você quiser autorizar os aplicativos do driver a fazer atualizações do Fleet Engine além das restritas à função de driver não confiável; como para algumas atualizações de tarefas, use o papel de Motorista Confiável. Para informações sobre um modelo que usa o papel de Motorista Confiável, consulte Modelo de driver confiável.
Para mais informações sobre os usos das funções de motorista confiáveis e não confiáveis, consulte Configuração do projeto do Cloud.
Planeje um dia de trabalho
A tabela a seguir descreve como é um dia de trabalho para motoristas de primeira ou última milha em uma empresa de entrega e logística. Sua empresa pode diferem nos detalhes, mas você pode ver como você pode modelar um dia de trabalho.
Tempo | Atividade | Modelagem |
---|---|---|
Dentro de 24 horas a partir do início do dia | O agente atribui remessas a veículos ou rotas de entrega. | É possível criar tarefas para entregas, retiradas, intervalos e
outros no Fleet Engine com antecedência. Por exemplo, é possível criar
tarefa de coleta de remessa,
tarefa de entrega de pedidos,
indisponibilidade programada;
parada programada.
Atribuir tarefas a um veículo quando o conjunto de pacotes de entrega e a ordem em que devem ser entregues estão finalizadas. |
Início do dia | O motorista começa o dia no depósito fazendo login no app. | Inicialize a API Delivery Driver. Crie o veículo de entrega no Fleet Engine, conforme necessário. |
O motorista carrega as remessas no veículo de entrega, digitalizando as remessas. | Se as tarefas de entrega da remessa não foram criadas antecipadamente, criar tarefas de entrega de frete no momento da verificação. | |
O motorista confirma a ordem das tarefas a serem realizadas. | Se elas não tiverem sido criadas com antecedência, crie tarefas de retirada no frete indisponibilidade programada; paradas programadas. | |
O driver sai do depósito e se compromete com o próximo número de tarefas a serem concluído. | Atribuir todas as tarefas ou um subconjunto de tarefas ao veículo, confirmando o pedido de conclusão. | |
O motorista entrega uma remessa. | Após chegar na parada de entrega, realize as ações relacionadas a um veículo chegando a uma parada. Depois de entregar o pacote, feche o tarefa de entrega e, como opção, status de remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes começar a dirigir até a próxima parada, realizar ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. | |
O motorista encontra um veículo alimentador para transferir remessas adicionais para o veículo de entrega. | Ponto de encontro para uma baldeação entre o feeder e os veículos de entrega
deve ser definida como uma parada programada.
Depois de transferir e escanear as remessas, crie tarefas de entrega caso ainda não tenham sido criados. Em seguida, atualize a conclusão da tarefa ordenar atribuindo tarefas a um veículo e atualizar a ordem das tarefas. |
|
O motorista recebe uma notificação de um pedido de retirada. | Depois de aceitar o pedido de retirada, criar uma tarefa de retirada de fretes. Em seguida, atualize a execução da tarefa ordenar atribuindo tarefas a um veículo e atualizar a ordem das tarefas. | |
Meio-dia | Motorista faz uma pausa para o almoço. | Se um local estiver associado à tarefa de indisponibilidade, trate-o como
qualquer outra tarefa. Realizar ações relacionadas a um veículo
chegar a uma parada,
veículo conclui uma parada
e veículo a caminho da próxima parada.
Caso contrário, nenhuma outra ação é necessária até o fim do intervalo. Remova a tarefa confirmando as tarefas seguintes e as restantes. Como atualizar a ordem das tarefas. |
O motorista pega uma remessa. | Isso é modelado como uma parada de entrega. Realizar ações relacionadas a um veículo chegando a uma parada fechar uma tarefa e, como opção, armazenar o status do envio e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. Observação: para garantir o faturamento correto, todas as retiradas precisam ter um tarefa de entrega. Se a retirada for entregue em outro local no do mesmo trajeto do motorista naquele dia, recomendamos modelar essa tarefa de entrega como qualquer outra tarefa de entrega no trajeto. Se o motorista estiver trazendo o pedido de retirada para o depósito, recomendamos criar uma tarefa de entrega no depósito destino. | |
O motorista faz uma parada programada para retirar as remessas em uma caixa de depósito. | Ela é modelada da mesma forma que qualquer outra parada de embarque. Realizar ações relacionadas a um veículo chegando a uma parada e encerrar uma tarefa. Depois de concluir todas as tarefas na parada e começando a dirigir até a próxima parada, realizar ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. | |
O motorista recebe uma notificação de que uma remessa foi desviada para um local alternativo. | Defina o status de entrega da remessa original como CONCLUÍDA e crie um novo tarefa de entrega da remessa para o novo local de entrega. Para mais informações, consulte Redirecionar uma remessa. | |
O motorista tentou entregar um pacote, mas não conseguiu. | Isso é semelhante a uma interrupção de entrega, marcando o a tarefa de entrega como concluída. Realizar ações relacionadas a um veículo chegando a uma parada. Depois falha na entrega da remessa, fechar a tarefa e, opcionalmente, status de remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. | |
O motorista foi notificado para reter (não entregar) uma remessa. | Após a notificação ser recebida e confirmada, defina o status da tarefa como CONCLUÍDA. | |
O motorista foi notificado para entregar determinada remessa em seguida, alterando o pedido de entrega confirmado. | Atualizar a ordem das tarefas. | |
O motorista decide entregar uma remessa fora de ordem. | Atualizar a ordem das tarefas e, em seguida, continue normalmente. | |
O motorista entrega várias encomendas para um único local. | Isso é modelado de maneira semelhante a uma única parada de entrega de remessa. Após chegar na parada, realize as ações relacionadas a um vehicle chegando em uma parada. Depois de entregar cada remessa, feche cada tarefa e, opcionalmente, status de envio da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. | |
Fim do dia | O motorista retorna ao depósito. | Se o motorista retornar ao depósito com remessas retiradas durante o você também precisa criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. Você pode fazer isso modelando o depósito como qualquer outra parada de entrega. Se o depósito não estiver sendo usado como parada de entrega, você ainda poderá, como opção, modelar o depósito como uma parada programada. Fazer um modelo da parada permite que os motoristas vejam o trajeto de volta à estação e mostrar o tempo estimado de chegada. |
Como funcionam as atualizações de localização
Para ter o melhor desempenho com o Fleet Engine, forneça a ele um fluxo atualizações de localização. Use uma das seguintes maneiras para fornecer essas atualizações:
- Use o SDK do Driver: Android, iOS a opção mais simples.
- Use código personalizado (útil se os locais forem redirecionadas pelo seu back-end, ou se você usa dispositivos que não sejam Android ou no iOS.
Independentemente de como você fornece atualizações de localização do veículo, seu back-end é responsável por atualizar o Fleet Engine quando um veículo de entrega é a caminho de uma parada (incluindo a estação) e quando chegar a uma parada. O Fleet Engine não detecta esses eventos automaticamente.
Paradas e locais de entrega de veículos
Uma parada de veículo é onde um veículo de entrega conclui uma tarefa de envio ou alguma outra tarefa. Ele é um ponto de acesso como uma plataforma de carregamento na via.
O local de entrega é o local em que o produto será entregue ou retirado. Pode ser necessário caminhar um pouco para ir e voltar do local de entrega na parada do veículo.
Por exemplo, quando um motorista entrega uma remessa de uma loja de um shopping, o veículo de entrega para no estacionamento do shopping perto a entrada mais próxima da loja. Esta é a parada do veículo. O motorista e depois caminha da parada do veículo até o local do shopping onde onde a loja está localizada. Esse é o local de entrega.
Para a melhor experiência de rastreamento de remessa para seus usuários, considere como as tarefas de remessa são atribuídas a paradas de veículos e tenha em mente que o número de as paradas restantes do veículo para as tarefas da remessa são informadas ao usuário para ajudar visualizar o progresso do envio.
Por exemplo, se um motorista está fazendo muitas entregas em um único prédio comercial, considere atribuir todas as tarefas de entrega a uma única parada de veículo. Se cada tarefa de entrega é atribuída a uma parada de veículo, a entrega experiência de acompanhamento seria menos útil para seus usuários, pois o acompanhamento é apenas disponível quando o veículo estiver dentro de um número limitado de paradas antes ao destino. Ter muitas paradas de veículos concluídas em um curto período não proporciona ao usuário muito tempo para acompanhar o progresso da entrega.
Usar os SDKs para dispositivos móveis
Antes de fazer chamadas para o SDK do Driver, inicialize-o.
Inicializar a API Delivery Driver
Antes de inicializar a API Delivery Driver no SDK do Driver, verifique se para inicializar o SDK do Navigation. Em seguida, inicialize a API Delivery Driver, conforme mostrado no exemplo a seguir:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Casos de uso
Esta seção descreve como usar a API Deliveries para modelar casos de uso comuns.
Identificadores exclusivos de entidade
O formato e o valor dos identificadores de entidade exclusivos usados em chamadas REST são opacas para o Fleet Engine. Evite usar IDs com incrementação automática e verifique se o identificador não contém informações de identificação pessoal (PII), como o número de telefone do motorista.
Criar um veículo
Você pode criar um veículo no SDK do driver ou de um ambiente de servidor usando gRPC ou REST.
gRPC
Para criar um veículo novo, faça uma chamada CreateDeliveryVehicle
para o Fleet Engine.
Use o objeto CreateDeliveryVehicleRequest
para definir os atributos do
o novo veículo de entrega. Qualquer valor especificado no campo Name
não será
ignorada de acordo com as orientações da API para IDs especificados pelo usuário.
Use o campo DeliveryVehicleId
para definir o ID do veículo.
Ao criar um DeliveryVehicle
, também é possível especificar estes campos:
- Atributos
- LastLocation
- Tipo
Não defina outros campos. Se você fizer isso, o Fleet Engine vai retornar um erro
porque esses campos são somente leitura ou só podem ser atualizados com uma chamada para
UpdateDeliveryVehicle
:
Para criar um veículo sem definir nenhum campo opcional, você pode deixar o
Campo DeliveryVehicle
não definido em CreateDeliveryVehicleRequest
.
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar um veículo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para criar um veículo em um ambiente de servidor, faça uma chamada REST HTTP
para CreateDeliveryVehicle
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> é um identificador exclusivo de um veículo de entrega na sua frota.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo POST representa a entidade DeliveryVehicle
a ser criada. É possível especificar
os seguintes campos opcionais:
- Atributos
- lastLocation
- tipo
Comando curl
de exemplo:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
O Fleet Engine ignora o campo name
da entidade DeliveryVehicle
de acordo com a orientação da API para IDs especificados pelo usuário.
Não defina outros campos. Se você fizer isso, o Fleet Engine vai retornar um erro
porque esses campos são somente leitura ou só podem ser atualizados usando uma chamada para
UpdateDeliveryVehicle
:
Para criar um veículo sem definir nenhum campo, deixe o corpo do POST
em branco. O veículo recém-criado extrai um ID de veículo do
o parâmetro deliveryVehicleId
no URL POST.
Comando curl
de exemplo:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Criar uma tarefa de retirada de frete
É possível criar uma tarefa de retirada de fretes no SDK do Driver ou de um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar uma tarefa de retirada de frete:
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 frete 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. Não pode ser o número de rastreamento para o envio. Se você não tem IDs de tarefas em seu sistema, pode gerar um identificador universalmente exclusivo (UUID).
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor tipo Type.PICKUP estado State.OPEN trackingId O número ou identificador que você está usando para rastrear um envio. plannedLocation O local em que a tarefa será concluída. Neste caso, o local de retirada do envio. taskDuration O tempo esperado, em segundos, que leva para retirar a remessa no local de retirada. Campos opcionais:
Campo Valor targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Isso não afetam o comportamento de roteamento. Atributos Uma lista de atributos de tarefas personalizados. Cada atributo precisa ter uma chave exclusiva.
Todos os outros campos da entidade são ignorados para criação. Lançamentos do Fleet Engine
uma exceção se a solicitação incluir um deliveryVehicleId
atribuído. Você atribui
usando UpdateDeliveryVehicleRequest
. Para mais informações, consulte
Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.
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"
}
}
EOM
Criar uma tarefa de entrega de remessa
Crie uma tarefa de entrega de remessa no SDK do Driver ou de um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar uma tarefa de entrega de remessa:
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 entrega de remessa em um ambiente de servidor usando gRPC ou REST, 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. Não pode ser o número de rastreamento para o envio. Se você não tem IDs de tarefas em seu sistema, pode gerar um identificador universalmente exclusivo (UUID).
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor tipo Type.DELIVERY estado State.OPEN trackingId O número ou identificador que você está usando para rastrear um envio. plannedLocation O local em que a tarefa será concluída. Neste caso, o local de entrega da remessa. taskDuration O tempo esperado, em segundos, que leva para a entrega do produto. no local de entrega. Campos opcionais:
Campo Valor targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Isso não afetam o comportamento de roteamento. Atributos Uma lista de atributos de tarefas personalizados. Cada atributo precisa ter uma chave exclusiva.
Todos os outros campos da entidade são ignorados para criação. Lançamentos do Fleet Engine
uma exceção caso a solicitação inclua um deliveryVehicleId atribuído. Você atribui
usando UpdateDeliveryVehicleRequest
. Para mais informações, consulte
Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.
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
Tarefas de criação em lote
É possível criar um lote de tarefas em um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar duas tarefas, uma para entrega e outra para retirada no mesmo local:
static final String PROJECT_ID = "my-delivery-co-gcp-project"; DeliveryServiceBlockingStub deliveryService = DeliveryServiceGrpc.newBlockingStub(channel); // Delivery Task settings Task deliveryTask = Task.newBuilder() .setType(Task.Type.DELIVERY) .setState(Task.State.OPEN) .setTrackingId("delivery-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Delivery Task request CreateTaskRequest createDeliveryTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8312508") // Task ID assigned by the Provider .setTask(deliveryTask) // Initial state .build(); // Pickup Task settings Task pickupTask = Task.newBuilder() .setType(Task.Type.PICKUP) .setState(Task.State.OPEN) .setTrackingId("pickup-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Pickup Task request CreateTaskRequest createPickupTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8241890") // Task ID assigned by the Provider .setTask(pickupTask) // Initial state .build(); // Batch Create Tasks settings String parent = "providers/" + PROJECT_ID; // Batch Create Tasks request BatchCreateTasksRequest batchCreateTasksRequest = BatchCreateTasksRequest.newBuilder() .setParent(parent) .addRequests(createDeliveryTaskRequest) .addRequests(createPickupTaskRequest) .build(); // Error handling // If Fleet Engine does not have any task(s) with these task ID(s) and the // credentials of the requestor pass, the service creates the task(s) // successfully. try { BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks( batchCreateTasksRequest); } 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 entrega e retirada em um ambiente de servidor, faça uma
Chamada REST HTTP para BatchCreateTasks
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, onde <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade BatchCreateTasksRequest
:
Campos obrigatórios:
Campo Valor solicitações Matriz < CreateTasksRequest
>Campos opcionais:
Campo Valor cabeçalho `DeliveryRequestHeader`
Cada elemento CreateTasksRequest
em requests
precisa passar pela mesma validação
como uma solicitação CreateTask
, com a exceção de que parent
e header
são opcionais. Se definidos, eles precisam ser idênticos a
os respectivos campos no nível superior BatchCreateTasksRequest
. Consulte
criar uma tarefa de retirada de fretes e
criar uma tarefa de entrega de remessa
para regras de validação específicas.
Para mais informações, consulte a documentação de referência da API para BatchCreateTasks
(gRPC, REST).
Comando curl
de exemplo:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Indisponibilidade programada
É possível criar uma tarefa indicando indisponibilidade (por exemplo, para motoristas quebras ou reabastecimento de veículos) da SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Uma tarefa de indisponibilidade programada não pode incluir um ID de acompanhamento. Também é possível informar um local.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar uma tarefa de indisponibilidade:
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
Para criar uma tarefa de indisponibilidade 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. Se você não IDs de tarefas no sistema, é possível gerar um ID exclusivo (UUID).
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor tipo Type.UNAVAILABLE estado State.OPEN taskDuration A duração do intervalo em segundos. Campos opcionais:
Campo Valor plannedLocation Local da pausa, se ela precisar ser realizada em um local específico.
Todos os outros campos da entidade são ignorados para criação. Lançamentos do Fleet Engine
uma exceção caso a solicitação inclua um deliveryVehicleId atribuído. Você atribui
usando UpdateDeliveryVehicleRequest
. Para mais informações, consulte
Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.
Comando curl
de exemplo:
# 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
Paradas programadas
É possível criar uma tarefa de parada programada no SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Uma tarefa de parada programada pode não incluir um ID.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para criar uma tarefa de parada programada:
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
Para criar uma tarefa de parada programada 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. Se você não tiver IDs de tarefas no sistema, poderá gerar um identificador universalmente exclusivo (UUID).
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor tipo Type.SCHEDULED_STOP estado State.OPEN plannedLocation O local da parada. taskDuration A duração prevista da parada em segundos. Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados para criação. Lançamentos do Fleet Engine
uma exceção caso a solicitação inclua um deliveryVehicleId atribuído. Você atribui
usando UpdateDeliveryVehicleRequest
. Para mais informações, consulte
Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.
Comando curl
de exemplo:
# 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
Definir janela de tempo desejada
A janela de tempo desejada TimeWindow durante o qual a tarefa deve ser concluída. Por exemplo, se você comunicar uma a janela de tempo de entrega aos destinatários, use o intervalo de tempo para capturar a janela de tempo e gerar alertas ou analisar o pós-viagem desempenho usando o campo.
A janela de horário desejado consiste em um horário de início e um de término e pode ser definido em qualquer tipo de tarefa. A janela de tempo desejada não afeta o roteamento do seu modelo.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para definir uma janela de tempo da tarefa:
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 UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<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> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Esta configuração não afeta o comportamento de roteamento Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de 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=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
Definir a configuração de visibilidade do rastreamento de tarefas
a visibilidade dos dados na biblioteca Shipment Tracking e desses dados;
retornados de uma chamada para GetTaskTrackingInfo
podem ser controlados em uma por tarefa
definindo uma
TaskTrackingViewConfig
na tarefa. Consulte
Tarefas com veículos ativos
para mais informações. Isso pode ser feito ao criar ou atualizar
tarefa. Veja a seguir um exemplo de como atualizar a tarefa com essa configuração:
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC Para definir a configuração da visualização de rastreamento de tarefas:
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 do rastreamento de tarefas usando HTTP, chame UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<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> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor taskTrackingViewConfig Configuração para o rastreamento de tarefas que especifica quais elementos de dados que são visíveis para os usuários finais em quais circunstâncias. Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de 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
Atribuir tarefas a um veículo
Você atribui tarefas a um veículo de entrega atualizando a ordem das tarefas para o veículo. A ordem das tarefas para um veículo é determinada pela lista de paradas para o veículo de entrega, e é possível atribuir uma ou mais tarefas a cada parada de veículo. Para mais detalhes, consulte Atualizar a ordem das tarefas.
Para transferir uma remessa de um veículo para outro, feche a tarefa original e recriá-la antes de atribuir o novo veículo a ela. Se você atualizar a tarefa ordenação para uma tarefa que já foi atribuída em um veículo diferente, ocorrerá um erro.
Atualizar a ordem das tarefas
É possível atualizar as tarefas atribuídas a um veículo que sejam realizadas as SDK do Driver, ou o ambiente do servidor. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.
Quando você atualiza a ordem de tarefas para um veículo, ele também faz o seguinte:
- Atribui tarefas novas ao veículo.
- Fecha todas as tarefas que foram atribuídas anteriormente ao veículo, mas que não foram na ordem atualizada.
Para transferir uma remessa de um veículo para outro, fechar a tarefa original e recriá-la antes de atribuir o novo veículo a ela. Se você atualizar a tarefa ordenação para uma tarefa que já foi atribuída em um veículo diferente, ocorrerá um erro.
Você pode atualizar a ordem das tarefas a qualquer momento.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para atualizar a ordem das tarefas para o veículo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para atualizar a ordem de tarefas de um veículo em um ambiente de servidor, faça uma chamada REST HTTP
para UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> é um identificador exclusivo de um veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade DeliveryVehicle
:
Campos obrigatórios:
Campo Valor remainingVehicleJourneySegments Uma lista de segmentos da jornada para tarefas na ordem em que devem ser executadas. A primeira tarefa da lista é executada primeiro. remainingVehicleJourneySegments[i].stop A parada da tarefa i na lista. remainingVehicleJourneySegments[i].stop.plannedLocation O local planejado para a parada. remainingVehicleJourneySegments[i].stop.tasks Uma lista de tarefas a serem realizadas nesta parada de veículo. remainingVehicleJourneySegments[i].stop.state State.NEW Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
O veículo está a caminho da próxima parada
O Fleet Engine precisa ser notificado quando um veículo sai de uma parada ou começa navegação. É possível notificar o Fleet Engine pelo SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para notificar o Fleet Engine que um veículo está a caminho da próxima parada.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para notificar o Fleet Engine que um veículo está a caminho da próxima parada a partir de um
ambiente servidor, faça uma chamada HTTP REST para UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade DeliveryVehicle
:
Campo obrigatório:
Campo Valor remainingVehicleJourneySegments Lista de paradas de veículos restantes com os estados marcados como State.NEW. A primeira parada da lista precisa ter o estado marcado como State.ENROUTE. Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na notificação.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Atualizar localização do veículo
Se você não estiver usando o SDK do motorista para atualizar a localização do veículo, faça uma uma chamada direta para o Fleet Engine com a localização do veículo. Para qualquer veículo ativo, O Fleet Engine espera uma atualização de local pelo menos uma vez por minuto e no máximo uma vez a cada 5 segundos.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para atualizar a localização de um veículo no Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para atualizar a localização de um veículo no Fleet Engine usando HTTP REST, faça uma chamada para
UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> é um identificador exclusivo do veículo de entrega na sua frota ou se você pretende atualizar o local. É o identificador que especificado ao criar o veículo.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade DeliveryVehicle
:
Campo obrigatório:
Campo Valor lastLocation.supplementalLocation A localização do veículo. lastLocation.supplementalLocationTime O último carimbo de data/hora conhecido em que o veículo esteve nesse local. lastLocation.supplementalLocationSensor Deve ser preenchido com CUSTOMER_SuppPLIED_LOCATION. Campos opcionais:
Campo Valor lastLocation.supplementalLocationAccuracy Precisão da localização fornecida, em metros.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
O veículo chega a uma parada
O Fleet Engine precisa ser notificado quando um veículo chega a uma parada. Você pode notificar do Fleet Engine SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para notificar a Fleet Engine que um veículo chegou a uma parada:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para notificar a Fleet Engine sobre a chegada de um veículo em uma parada em um ambiente de servidor,
faça uma chamada HTTP REST para UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade DeliveryVehicle
:
Campos obrigatórios:
Campo Valor remainingVehicleJourneySegments A parada à qual você chegou com estado definido como State.ARRIVED, seguido por uma lista de paradas de veículos restantes com seus estados marcados como State.NEW. Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
O veículo conclui uma parada
O Fleet Engine precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada a serem definidas para o estado CLOSED. Você pode notifique o Fleet Engine pelo SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para notificar o Fleet Engine de que um veículo concluiu uma parada.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para notificar o Fleet Engine sobre a conclusão de uma parada em um ambiente de servidor,
faça uma chamada HTTP REST para UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade DeliveryVehicle
:
Campos obrigatórios:
Campo Valor remaining_vehicle_journey_segments A parada concluída não deve mais estar na lista de paradas de veículos restantes. Campos opcionais:
- Nenhum
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Atualizar uma tarefa
A maioria dos campos de tarefa é imutável. No entanto, é possível modificar o estado, resultado da tarefa, hora do resultado da tarefa, local do resultado da tarefa e atributos, atualizando diretamente a entidade de tarefa. Por exemplo, nos casos em que uma tarefa não foi atribuído a um veículo, você pode fechar a tarefa atualizando o estado diretamente.
gRPC
Este é um exemplo de atualização de uma tarefa por meio do gRPC.
REST
Este é um exemplo de atualização de uma tarefa pelo REST.
Fechar uma tarefa
Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada em que a tarefa ocorre ou removê-lo da lista de paradas de veículos. Para fazer isso, você pode definir a lista de o veículo restante para, assim como ao atualizar a ordem das tarefas; para um veículo.
Se uma tarefa ainda não tiver sido atribuída a um veículo e precisar ser fechada, atualize a tarefa para o estado CLOSED. No entanto, não é possível reabrir uma tarefa CLOSED.
O fechamento de uma tarefa não indica sucesso ou falha. Ele indica que o tarefa não é mais considerada em andamento. Para o rastreamento de frotas, é importante indicar o resultado real de uma tarefa para que uma entrega pode ser mostrado.
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)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.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 marcar uma tarefa como fechada em um ambiente de servidor, faça uma chamada HTTP REST para
UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<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> é um token emitido por uma fábrica de tokens do Fleet Engine.
Você precisa incluir uma entidade Task
no corpo da solicitação:
Campos obrigatórios:
Campo Valor estado State.CLOSED Campos opcionais:
Campo Valor taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED taskOutcomeTime A hora em que a tarefa foi concluída. taskOutcomeLocation O local em que a tarefa foi concluída. O padrão do Fleet Engine é ao último local do veículo, a menos que seja substituído manualmente pelo provedor.
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de 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=state,taskOutcome,taskOutcomeTime" \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${JWT}" \ --data-binary @- << EOM { "state": "CLOSED", "taskOutcome": "SUCCEEDED", "taskOutcomeTime": "$(date -u --iso-8601=seconds)" } EOM
Definir o resultado da tarefa e o local dos resultados
O encerramento de uma tarefa não indica sucesso ou falha, mas indica que a tarefa não é mais considerada em andamento. Para o rastreamento de frotas, é importante indicar o resultado real de uma tarefa para que o resultado da entrega pode ser mostrado e há cobrança adequada pelos serviços. Depois de definido, não é possível mudar o resultado da tarefa. No entanto, é possível modificar o horário e o local do resultado da tarefa depois de terem sido definidos.
Tarefas que estão no estado FECHADO podem ter seus resultados definidos como CONCLUÍDA ou COM FALHA. O Fleet Engine cobra apenas as tarefas de entrega com estado de CONCLUÍDA.
Ao marcar o resultado de uma tarefa, o Fleet Engine preenche automaticamente o local do resultado da tarefa com a última localização conhecida do veículo. Você pode substituir esse comportamento.
gRPC
Você tem a opção de definir o local do resultado da tarefa ao definir o resultado. Definir o local impede que o Fleet Engine o configure para o padrão da última localização do veículo. Também é possível substituir o local do resultado da tarefa do Fleet Engine definidos posteriormente. O Fleet Engine nunca substitui um local de resultado de tarefa que você fornece. Não é possível definir um local de resultados de tarefa para uma tarefa que não tem um conjunto de resultados de tarefa. É possível definir o resultado da tarefa e local do resultado da tarefa dentro da mesma solicitação.
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para definir o resultado de uma tarefa como CONCLUÍDO e definir o local onde a tarefa foi concluído:
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)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.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 marcar uma tarefa como concluída em um ambiente de servidor,
faça uma chamada HTTP REST para UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<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> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa conter uma entidade Task
:
Campos obrigatórios:
Campo Valor taskOutcome Outcome.SUCCEEDED ou Outcome.FAILED Campos opcionais:
Campo Valor taskOutcomeLocation O local em que a tarefa foi concluída. Se não for definido, o Fleet Engine o padrão é a última localização do veículo. taskOutcomeTime O carimbo de data/hora em que a tarefa foi concluída.
Todos os outros campos da entidade são ignorados na atualização.
Comando curl
de 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=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Redirecionar uma remessa
Depois que uma tarefa de remessa é criada, o local planejado não pode ser alterado. Para redirecionar uma remessa, feche a tarefa de envio sem configurar um resultado e, em seguida, criar uma nova tarefa com o local planejado atualizado. Depois de criar a nova tarefa, atribua-a ao mesmo veículo. Para mais informações, consulte fechar a tarefa de envio e atribuir a tarefa.
Usar alimentador e veículos de entrega
Se você usa veículos alimentadores para transportar remessas para veículos de entrega ao longo do dia, modelar a transferência de remessas como uma tarefa de parada programada para o veículo de entrega. Para garantir um rastreamento de localização preciso, atribua uma tarefa de entrega para uma remessa transferida depois que ela é carregada na veículo de entrega. Para mais informações, consulte parada programada.
Armazenar status de envio e outras metainformações
Quando uma tarefa de remessa é concluída, o estado da tarefa e o resultado são registrados na tarefa. No entanto, convém atualizar outras metainformações específicas da remessa. Para armazenar outras metainformações que você pode referência fora do serviço do Fleet Engine, use o "tracking_id" associado com a tarefa como uma chave em uma tabela externa.
Para mais informações, consulte O ciclo de uma tarefa.
Procurar um veículo
Você pode procurar um veículo no SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para procurar um veículo:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para procurar um veículo em um ambiente de servidor,
faça uma chamada HTTP REST para GetVehicle
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> é um identificador exclusivo da tarefa.
<vehicleId> é o ID do veículo a ser pesquisado.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa estar vazio.
Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir uma entidade de veículo.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Procurar uma tarefa
É possível pesquisar uma tarefa em um ambiente de servidor usando gRPC ou REST. O SDK do Driver não suporte à procura de uma tarefa.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para procurar uma tarefa:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para procurar uma tarefa em um ambiente de servidor,
faça uma chamada HTTP REST para GetTask
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id> é um identificador exclusivo da tarefa.
<taskId> é o código da tarefa a ser pesquisada.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
O corpo da solicitação precisa estar vazio.
Se a pesquisa for bem-sucedida, o corpo da resposta conterá uma entidade de tarefa.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
Procurar as informações da tarefa de envio pelo ID de rastreamento
É possível procurar informações sobre as tarefas da frota das seguintes maneiras: cada uma com uma finalidade diferente:
- por um ID de tarefa: usado por usuários, como operadores de frota que têm acesso ao visualização completa dos dados da tarefa.
- por um ID de acompanhamento: usado pelo seu software cliente para fornecer informações informações para um usuário final, como quando um pacote é esperado na casa dele.
Esta seção discute a busca de informações de tarefas por um ID de acompanhamento. Se você quiser Para procurar uma tarefa pelo ID, acesse Procurar uma tarefa.
Para procurar informações por um ID de acompanhamento, você pode usar uma das seguintes opções:
Requisitos de pesquisa
As informações do envio fornecidas por um ID de rastreamento estão em conformidade com as regras de visibilidade afirmado em Controlar a visibilidade dos locais rastreados.
Use o Fleet Engine para procurar informações de envio pelo ID de rastreamento. O motorista O SDK não aceita pesquisas de informações por ID de acompanhamento. Para fazer isso com a Fleet Engine, use um ambiente de servidor ou de navegador.
Use o token mais estreito possível para limitar os riscos de segurança. Por exemplo, se você use um token de consumidor de entrega, todas as chamadas da API Fleet Engine Deliveries retornarão apenas informações relevantes para esse usuário final, como o remetente ou o destinatário de uma remessa. Todas as outras informações nas respostas são encobertas. Para mais informações sobre tokens, consulte Crie um JSON Web Token (JWT) para autorização.
Pesquisas com Java usando gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para procurar informações sobre uma tarefa de envio pelo ID de rastreamento.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Pesquisas usando HTTP
Para procurar uma tarefa de remessa em um navegador, faça uma chamada REST HTTP para
GetTaskTrackingInfo
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> é o ID de acompanhamento associado à tarefa.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, onde <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
Se a pesquisa for bem-sucedida, o corpo da resposta conterá uma taskTrackingInfo com uma entidade conhecida.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Listar tarefas
É possível listar tarefas de um ambiente de servidor ou de navegador. O SDK do Driver não dão suporte à listagem de tarefas.
A listagem de tarefas solicita amplo acesso às tarefas. A listagem de tarefas é destinada apenas a usuários confiáveis. Usar o leitor de frota de entrega ou a autenticação de superusuário de entrega Tokens ao fazer solicitações de tarefas de lista.
As tarefas listadas têm os seguintes campos encobertos:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
As tarefas listadas podem ser filtradas pela maioria das propriedades de tarefa. Para a sintaxe da consulta de filtro, consulte AIP-160 (link em inglês). A lista a seguir mostra as tarefas válidas que podem ser usadas para filtragem:
- Atributos
- delivery_vehicle_id
- estado
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- tipo
Use os seguintes formatos de campo com base nas propostas de melhoria da API do Google:
Tipo de campo | Formato | Exemplo |
---|---|---|
Carimbo de data/hora | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
Duração | Número de segundos seguidos por um s |
task_duration = 120s |
Enumeração | String | state = CLOSED AND type = PICKUP |
Local | point.latitude e point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Acesse AIP-160 para ver a lista completa de consultas de filtro operadores.
Se nenhuma consulta de filtro for especificada, todas as tarefas serão listadas.
As listas de tarefas são paginadas. Um tamanho de página pode ser especificado em solicitações de lista de tarefas. Se um tamanho de página for especificado, o número de tarefas retornadas não será maior que o tamanho de página especificado. Se nenhum tamanho de página estiver presente, um padrão razoável é usado. Se o tamanho da página solicitado exceder um valor máximo interno, então o máximo interno é usado.
Uma lista de tarefas pode incluir um token para leitura da próxima página de resultados. Use o token da página com uma solicitação que seja idêntica à anterior para recuperar a próxima página de tarefas. Quando o token de página retornado estiver vazio, não haverá mais tarefas disponíveis para recuperação.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para listar tarefas para um deliveryVehicleId e um atributo de tarefa. Um bem-sucedido a resposta poderá ficar em branco. Uma resposta vazia indica que não há Tarefas associou o deliveryVehicleId fornecido.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para listar tarefas em um navegador, faça uma chamada REST HTTP para ListTasks
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Para aplicar um filtro às tarefas listadas, inclua um "filtro" Parâmetro de URL com uma consulta de filtro com escape de URL como valor.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir dados com a estrutura a seguir:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que não foram encontradas tarefas que atendem aos critérios de filtro especificados.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Listar veículos de entrega
É possível listar veículos de entrega de um ambiente de servidor ou navegador. O motorista O SDK não aceita a listagem de veículos de entrega.
A listagem de veículos de entrega solicita amplo acesso a veículos de entrega e é destinados apenas a usuários confiáveis. Usar Leitor de frota de entrega ou Super Entrega Tokens de autenticação do usuário ao fazer solicitações de veículos de entrega de listas.
Os veículos de entrega listados têm os seguintes campos encobertos devido ao impacto no tamanho da resposta:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
É possível filtrar os veículos de entrega da lista pela propriedade attributes
. Para
exemplo, para consultar um atributo com a chave my_key
e o valor my_value
, use
attributes.my_key = my_value
Para consultar vários atributos, mescle as consultas
usando os operadores lógicos AND
e OR
, como em attributes.key1 = value1 AND
attributes.key2 = value2
. Consulte AIP-160 para uma
descrição da sintaxe da consulta de filtro.
É possível filtrar os veículos de entrega listados por local usando a solicitação viewport
.
. O parâmetro de solicitação viewport
define janelas de visualização usando dois limites
coordenadas: latitude e longitude high
(nordeste) e low
(sudoeste)
de coordenadas. As solicitações serão rejeitadas se contiverem uma latitude alta.
geograficamente menor que uma latitude baixa.
Por padrão, as listas de veículos de entrega são paginadas com um tamanho de página razoável. Se você especificar um tamanho de página, a solicitação retornará apenas o número de veículos especificado pelo limite ou menos. Se o tamanho da página solicitado exceder um tamanho então o máximo interno será usado. As páginas padrão e máxima são 100 veículos.
Uma lista de veículos de entrega pode incluir um token para ler a próxima página de resultados. Um token de página só estará presente em uma resposta quando mais páginas de entrega veículos disponíveis para recuperação. Para acessar a próxima página de tarefas, use o token da página com uma solicitação que é idêntica à anterior solicitação.
gRPC
O exemplo a seguir mostra como usar o Biblioteca Java gRPC para listar veículos de entrega em uma região específica com um determinado atributo. Um resposta bem-sucedida ainda pode estar em branco. Quando isso acontece, significa que nenhuma veículos com o atributo especificado já estão na janela de visualização especificada.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para listar tarefas em um navegador, faça uma chamada REST HTTP para ListDeliveryVehicles
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Para aplicar um filtro às tarefas listadas, inclua um "filtro" parâmetro de URL com um como o valor da consulta de filtro com escape do URL.
O cabeçalho da solicitação precisa conter um campo Authorization com o valor. Bearer <token>, em que <token> é um token emitido por uma fábrica de tokens do Fleet Engine.
Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir dados com a estrutura a seguir:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Uma resposta bem-sucedida ainda pode estar vazia. Quando isso acontece, significa que nenhuma foram encontrados veículos de entrega que atendem à consulta de filtro e à janela de visualização especificadas.
Comando curl
de exemplo:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Rastreamento de frotas
Você tem duas opções para usar a API Fleet Engine Deliveries para ativar o rastreamento da frota:
Preferencial:use o Biblioteca JavaScript de rastreamento de frota. A biblioteca mostra a localização de veículos e locais de interesse rastreado pelo Fleet Engine. Contém um componente de mapa JavaScript. que é uma substituição simples para um objeto google.maps.Map padrão, e os componentes de dados para conexão com o Fleet Engine. Esse componente permite que você ofereça uma experiência personalizável e animada de rastreamento de frotas do seu aplicativo da Web ou para dispositivos móveis.
Implemente o rastreamento de frota próprio na API Fleet Engine Deliveries.
O segredo é procurar tarefas da frota pelo ID de acompanhamento.
Logging
É possível configurar o Fleet Engine para enviar registros de RPC ao Cloud Logging. Para mais informações, consulte Geração de registros.
Papéis e tokens de autorização
Conforme descrito em Gerenciar o ciclo de vida do veículo e da tarefa e notas de autorização para casos de uso individuais, tornando chamadas para o Fleet Engine requerem autenticação com JSON Web Tokens assinado com as credenciais da conta de serviço. As contas de serviço usadas esses tokens podem ter um ou mais papéis, sendo que cada papel concede um conjunto diferente de permissões.
Para mais informações, consulte Autenticação e autorização.
Solução de problemas comuns
Consulte as seções a seguir para receber ajuda se você tiver algum problema.
Resiliência
A Fleet Engine não é considerada uma fonte de verdade. Você é responsável para restaurar o estado do sistema, se necessário, sem depender de Fleet Engine.
Estado perdido no Fleet Engine
Ao trabalhar com o Fleet Engine, implemente os clientes para melhorar o sistema por conta própria em caso de falha. Por exemplo, quando o Fleet Engine tenta atualizar um veículo, ele poderá responder com um erro indicando que o veículo não está existem. O cliente precisa recriar o veículo no novo estado. Embora esse problema raramente ocorre, verifique se o sistema é resiliente o suficiente para lidar reimplantá-lo.
No cenário extremamente improvável de uma falha catastrófica do Fleet Engine, pode ser necessário recriar a maioria ou todos os veículos e tarefas. Se a taxa de criação ficar muito alto, algumas solicitações poderão falhar novamente devido a problemas de cota, já que verificações de cota em vigor para evitar ataques de negação de serviço (DOS). Nesse caso, diminua a taxa de recriação usando uma estratégia de espera para de novas tentativas.
Perda de estado no app do motorista
Se o app do motorista falhar, o app vai precisar recriar o estado atual. no SDK do Driver. O app deve tentar recriar tarefas para garantir que eles existem e restaurar os estados atuais. O app também precisa recriar e definir explicitamente a lista de paradas do SDK do Driver.
Perguntas frequentes
E se um motorista parar devido a uma tarefa fora de ordem?
Nesse caso, primeiro atualize a ordem das tarefas e continue normalmente. marcar a chegada na parada, a conclusão da tarefa e outros detalhes. Caso contrário, o sistema pode ficar inconsistente, os HECs podem ficar incorretos, e erros inesperados podem ser relatados.