Modele as atividades da frota para a primeira e a última milha de entregas com a API Fleet Engine Deliveries. Use 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 mais informações sobre as etapas a serem seguidas no console e como criar um JSON Web Token para autorização, consulte Autenticação e autorização.
Para 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 se é possível criar um veículo de entrega. Verificar a configuração imediatamente garante que você tenha resolvido problemas comuns de autorização que podem surgir durante a configuração do seu projeto. Há duas maneiras de verificar sua configuração:
Teste duas partes principais da configuração: assinatura do token de autorização e criação de veículo de entrega de teste com o utilitário de linha de comando
gcloud
. Para mais detalhes, consulte o guia Como verificar sua configuração.Teste sua configuração com os exemplos de scripts de autenticação do Fleet Engine.
Bibliotecas de cliente
Para uma melhor experiência de desenvolvedor com gRPC ou REST bruto, use as bibliotecas de cliente em várias linguagens de programação comuns. Para instruções sobre como conseguir bibliotecas de cliente para seu aplicativo de servidor, consulte Bibliotecas de cliente.
Os exemplos em Java nesta documentação pressupõem que você esteja familiarizado com o gRPC.
Estruturas de dados
A API Fleet Engine Deliveries usa duas estruturas de dados para modelar a coleta e a entrega de remessas:
- O veículo de entrega usado para transportar a remessa.
- As tarefas de coleta e entrega de remessas.
Elas também servem para estimar os intervalos dos motoristas e as 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 retirada para o depósito. Em alguns casos, eles também podem transportar uma remessa diretamente do local de retirada para o local de entrega.
Use o SDK do Driver para criar um objeto DeliveryVehicle
no Fleet Engine
e enviar atualizações de localização para rastreamento de remessa e frota.
DeliveryVehicle
.
Tarefas
Você atribui tarefas de acordo com o tipo de ação que um veículo realiza durante o dia:
- Para retiradas e entregas, atribua Tarefas de envio.
- Para os momentos em que os motoristas estiverem indisponíveis, como intervalos obrigatórios, atribua Tarefas de indisponibilidade.
- Para tarefas que não são de direção em caixas de depósito ou locais de clientes, atribua tarefas de parada programada.
Cada tarefa atribuída precisa ter um ID exclusivo, mas elas podem compartilhar o mesmo ID de acompanhamento. Quando o Fleet Engine calcula as janelas de HEC para cada tarefa, ele usa todas elas e a ordem em que estão programadas para fazer estimativas. Para saber mais sobre IDs de tarefas, consulte Diretrizes de IDs de tarefas.
Para criar tarefas no Fleet Engine, use o gerenciador de tarefas do SDK do driver.
Tarefas de envio
Criar tarefas para retirada e entrega de uma remessa e incluir as seguintes informações:
- O local da retirada ou entrega.
- Um número de rastreamento ou ID.
- Um tempo de permanência para contabilizar o tempo adicional para concluir a tarefa, procurar estacionamento ou caminhar até o local de entrega.
- Um ID de tarefa exclusivo. Consulte Diretrizes do ID da tarefa.
Para encontrar mais informações, consulte os seguintes tópicos:
Android
iOS
Tarefas de indisponibilidade
As tarefas de indisponibilidade abrangem períodos em que um veículo não está disponível para retiradas ou entregas, como pausas para reabastecer o veículo ou para descanso do motorista.
Crie uma tarefa de indisponibilidade com as seguintes informações:
- A duração do intervalo.
- O local do intervalo (opcional). Você não precisa informar um local específico, mas fazer isso fornece janelas de HEC mais precisas ao longo do dia.
Para encontrar mais informações, consulte os seguintes tópicos:
Android
iOS
Tarefas de parada agendadas
Crie tarefas de paradas programadas para estimar as paradas que um veículo de entrega precisa fazer. Por exemplo, crie uma tarefa de parada programada para uma parada de coleta programada diária em um local específico, independentemente de outras entregas ou retiradas no mesmo local. Também é possível criar tarefas de parada programadas para coletas de caixas de depósito ou para modelar transferências de veículos alimentadores ou paradas em centros de serviços e pontos de serviço.
Para encontrar mais informações, consulte os seguintes tópicos:
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) nem dados de texto claros.
- Use strings Unicode válidas.
- Use até 64 caracteres.
- Não inclua nenhum destes caracteres ASCII: "/", ":", "\", "?" ou "#".
- Normalize de acordo com o Formulário C de normalização Unicode.
Veja a seguir alguns exemplos de bons IDs de tarefas:
- 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 | Viola PII e requisitos de caracteres: vírgulas, pontos, dois-pontos e barras. |
JohnDoe-577b484da26f-Cupertino-SantaCruz | Viola os requisitos de PII. |
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Viola PII e requisitos de caracteres: espaços em branco, vírgulas e aspas. Mais de 64 caracteres. |
Mais recursos
Para ver os campos específicos contidos em cada estrutura de dados, 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 da primeira ou da ú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.
- Um ID de veículo do cliente.
Use IDs 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 objetos DeliveryVehicle
que não
foram atualizados usando UpdateDeliveryVehicle
após sete dias. Para verificar 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 campo filter
que pode limitar as entidades DeliveryVehicle
retornadas àquelas com os
atributos especificados. DeliveryVehicleAttribute
não afeta o comportamento de roteamento do
Fleet Engine.
Não inclua informações de identificação pessoal (PII) ou informações sensíveis nos atributos, porque esse campo pode ficar visível para os usuários.
O ciclo 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 ao longo
do ciclo de vida. Os valores mudam de OPEN para CLOSED. As 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 na parada de veículo atribuída à tarefa.
Diretrizes da tarefa
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 como CLOSED automaticamente.
Quando o veículo da tarefa conclui a parada:
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 dela é definido como CLOSED automaticamente. Para saber mais, consulte Monitorar sua frota com a biblioteca JavaScript Fleet Tracking.
Assim como os veículos, o Fleet Engine exclui tarefas que não foram atualizadas após sete dias e, se você tentar criar uma tarefa com um ID que já existe, retornará um erro.
Observação:o Fleet Engine não oferece suporte à exclusão explícita de uma tarefa. O serviço exclui tarefas automaticamente após sete dias sem atualizações. Se você quiser reter dados de tarefas por mais de sete dias, implemente esse recurso 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, number
e booleano. A API ListTasks
inclui um campo filter
que pode limitar entidades
Task
retornadas àquelas com os atributos especificados. Os atributos de tarefa não
afetam o comportamento de roteamento do Fleet Engine.
Não inclua informações de identificação pessoal (PII) ou outras informações sensíveis nos atributos, porque eles podem ficar visíveis para os usuários.
Gerenciar o ciclo de vida do veículo e da tarefa
Lembrete: seu sistema interno atua como a fonte confiável de dados que a API Fleet Engine Deliveries amplia em seu nome.
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 tarefas associadas.
Ao mesmo tempo, o aplicativo do driver se comunica diretamente com o Fleet Engine para atualizar as informações de localização e rota do dispositivo. Esse modelo permite que o Fleet Engine gerencie com eficiência a localização em tempo real. Ele envia a localização diretamente para a biblioteca de rastreamento, que pode ser usada para atualizar o status do pedido dos consumidores.
Por exemplo, suponha que você tenha o seguinte cenário:
- Um motorista se aproxima de uma parada de entrega. O aplicativo do driver envia a localização ao Fleet Engine.
- O Fleet Engine envia a localização do dispositivo para a biblioteca de rastreamento, que é usada pelo app de consumidor para alertá-lo sobre a proximidade do pacote.
- Depois que o motorista conclui o envio, ele clica no botão "Envio entregue" no aplicativo do motorista.
- A ação "Envio entregue" envia as informações para seu sistema de back-end, que executa as etapas necessárias de validação e verificação da empresa.
- O sistema confirma a tarefa como CONCLUÍDA e atualiza o Fleet Engine usando a API Deliveries.
O diagrama a seguir ilustra esses processos em um nível genérico. Também mostra a relação padrão entre seu sistema, o cliente e o Fleet Engine.
Gerenciar tokens do cliente
As atualizações de localização originadas do aplicativo de driver e enviadas diretamente ao Fleet Engine exigem tokens de autorização. Esta é a abordagem recomendada para processar atualizações do cliente para o Fleet Engine:
Gere o token usando o papel da conta de serviço Usuário de driver não confiável de entrega do Fleet Engine.
Forneça um token de escopo limitado ao aplicativo do driver. Este escopo só permite atualizar a localização do dispositivo no Fleet Engine.
Essa abordagem garante que as chamadas originadas de dispositivos móveis, considerados ambientes de baixa confiança, sigam o princípio de privilégio mínimo.
Outros papéis da conta de serviço
Se, em vez disso, você quiser autorizar os aplicativos de driver a fazer atualizações diretas do Fleet Engine além daquelas restritas ao papel de driver não confiável, como para determinadas atualizações de tarefas, use o papel de driver confiável. Para saber mais sobre um modelo que usa o papel de driver confiável, consulte Modelo de driver confiável.
Para mais informações sobre o uso de papéis de driver não confiáveis e confiáveis, consulte Configuração de projetos do Cloud.
Modelar um dia de trabalho
A tabela a seguir descreve como pode ser um dia de trabalho para motoristas de primeira ou última milha para uma empresa de entrega e logística. Os detalhes da sua empresa podem variar, mas você pode ver como modelar um dia de trabalho.
Tempo | Atividade | Modelagem |
---|---|---|
Até 24 horas antes do início do dia | O agente atribui remessas a veículos ou rotas de entrega. | É possível criar tarefas para entregas de remessas, retiradas, quebras e
outras no Fleet Engine com antecedência. Por exemplo, é possível criar uma
tarefa de retirada,
tarefa de entrega de envio,
indisponibilidade programada ou
parada programada.
Atribua tarefas a um veículo depois que o conjunto de pacotes de entrega e a ordem em que precisam ser entregues forem finalizados. |
Início do dia | O motorista começa o dia no depósito fazendo login no app dele. | 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 de remessa não foram criadas com antecedência, crie tarefas de entrega de remessa no momento da leitura. | |
O motorista confirma a ordem das tarefas a serem realizadas. | Se elas não foram criadas com antecedência, crie tarefas de retirada de remessa, indisponibilidade programada e paradas programadas. | |
O driver sai do depósito e realiza a confirmação para o próximo número de tarefas a serem concluídas. | Atribua todas as tarefas ou um subconjunto de tarefas ao veículo, confirmando a ordem de conclusão. | |
Motorista entrega uma encomenda | Depois de chegar à parada de entrega, realize ações relacionadas a um veículo que chega a uma parada. Depois de entregar a remessa, feche a tarefa de entrega e, se quiser, o status da 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 o veículo conclui uma parada e ao viajar até a próxima parada. | |
O motorista encontra um veículo alimentador para transferir outros envios para o veículo de entrega. | O ponto de encontro para uma baldeação entre o alimentador e os veículos de entrega precisa ser modelado como uma parada programada.
Depois de transferir e verificar as remessas, crie tarefas de entrega, caso elas ainda não tenham sido criadas. Em seguida, atualize a ordem de conclusão da tarefa atribuindo tarefas a um veículo e atualizando a ordem das tarefas. |
|
O motorista recebe uma notificação de pedido de retirada. | Depois de aceitar o pedido de retirada, crie uma tarefa de retirada. Em seguida, atualize a ordem de execução atribuindo tarefas a um veículo e atualizando 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 chegando em uma parada, o veículo conclui uma parada e o veículo até a próxima parada.
Caso contrário, nenhuma outra ação será necessária até o fim do intervalo. Remova a tarefa confirmando as próximas e restantes e atualizando a ordem das tarefas. |
Motorista pega uma remessa. | Isso é modelado como uma parada de entrega. Realizar ações relacionadas a um veículo que chega a uma parada e fechar uma tarefa e, opcionalmente, armazenar o status da remessa e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada. Observação: para garantir o faturamento correto, todas as retiradas precisam ter uma tarefa de entrega correspondente. Se a retirada precisar ser entregue em outro local no 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 a coleta de volta para o depósito, recomendamos criar uma tarefa de entrega no destino do depósito. | |
O motorista faz uma parada programada para retirar as encomendas em uma caixa de depósito. | Ele é modelado como qualquer outro ponto de embarque. Realizar ações relacionadas a um veículo chegando a uma parada e fechar uma tarefa. Depois de concluir todas as tarefas e começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada. | |
O motorista recebe uma notificação sobre uma remessa sendo desviada para um local alternativo. | Defina o status da tarefa de entrega original como CONCLUÍDA e crie uma nova tarefa de entrega para o novo local. Para mais informações, consulte Redirecionar uma remessa. | |
O motorista tentou entregar um pacote, mas não conseguiu. | Isso é modelado de maneira semelhante a uma parada de entrega bem-sucedida, marcando a tarefa de entrega como concluída. Realize ações relacionadas a um veículo que chega a uma parada. Depois de não entregar a remessa, feche a tarefa e, opcionalmente, armazene o status da remessa e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada. | |
O motorista foi notificado para reter (não entregar) uma remessa. | Depois que a notificação for recebida e confirmada, defina o status da tarefa como CONCLUÍDA. | |
O motorista foi notificado para entregar determinada remessa em seguida, alterando a ordem de entrega confirmada. | Atualizar a ordem das tarefas. | |
O motorista escolhe entre entregar uma encomenda fora de ordem. | Atualize a ordem das tarefas e continue normalmente. | |
o motorista entrega várias encomendas para um único local. | Isso é modelado de forma semelhante a uma única parada de entrega de remessa. Depois de chegar à parada, realize ações relacionadas a um veículo chegando a uma parada. Depois de entregar cada remessa, feche cada tarefa e, opcionalmente, o status da remessa da loja e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada. | |
Fim do dia | O motorista volta ao depósito. | Se o motorista retornar ao depósito com encomendas coletadas durante o trajeto, você também precisará criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. Para fazer isso, modele o depósito como qualquer outra parada de entrega. Se o depósito não estiver sendo usado como uma parada de entrega, ele ainda poderá ser modelado como uma parada programada. Com eles, os motoristas podem ver o trajeto de volta ao depósito, além de mostrar o horário estimado de chegada. |
Como funcionam as atualizações de localização
Para ter o melhor desempenho com o Fleet Engine, forneça um fluxo de atualizações de localização do veículo. Use uma das seguintes maneiras para fazer isso:
- A opção mais simples é usar o SDK do Driver, Android ou iOS.
- Use código personalizado. Isso é útil se os locais forem realçados pelo seu back-end ou se você usa dispositivos que não são Android ou iOS.
Independentemente de como você fornece atualizações de localização do veículo, o back-end é responsável por atualizar o Fleet Engine quando um veículo de entrega está entrando em uma parada (incluindo o depósito) e quando ele chega a outra parada. O Fleet Engine não detecta esses eventos automaticamente.
Paradas de veículos e locais de entrega
Uma parada de veículo é quando um veículo de entrega conclui uma tarefa de envio ou alguma outra tarefa. Ele é um ponto de acesso, como uma base de carregamento ou um local de trajeto.
O local de entrega é o local onde a remessa será entregue ou retirada. Para ir e voltar do local de entrega, pode ser necessário caminhar da parada do veículo.
Por exemplo, quando um motorista está entregando uma remessa em uma loja de um shopping, o veículo de entrega para no estacionamento do shopping próximo à entrada mais próxima da loja. Esta é a parada do veículo. Em seguida, o motorista caminha da parada do veículo até o local dentro do shopping onde a loja está localizada. Este é o local de entrega.
Para ter a melhor experiência de rastreamento de frete para seus usuários, considere como as tarefas de envio são atribuídas às paradas de veículos e lembre-se de que o número de paradas de veículos restantes para tarefas de envio é relatado ao usuário para ajudá-lo a visualizar o progresso do envio.
Por exemplo, se um motorista está fazendo muitas entregas em um único escritório, considere atribuir todas as tarefas de entrega a uma única parada de veículo. Se cada tarefa de entrega for atribuída à própria parada do veículo, sua experiência de rastreamento de envio será menos útil para os usuários, porque o rastreamento só estará disponível quando o veículo estiver dentro de um número limitado de paradas antes do destino. Ter muitas paradas de veículos concluídas em um curto período não dá ao usuário muito tempo para acompanhar o progresso da entrega.
Usar SDKs para dispositivos móveis
Antes de fazer qualquer chamada para o SDK do Driver, inicialize-o.
Inicializar a API Delivery Driver
Antes de inicializar a API Delivery Driver no SDK Driver, inicialize 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 opacos para o Fleet Engine. Evite usar IDs de incremento automático e verifique se o identificador não contém informações de identificação pessoal (PII, na sigla em inglês), como o número de telefone do motorista.
Criar um veículo
É possível criar um veículo a partir do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST.
gRPC
Para criar um novo veículo, faça uma chamada CreateDeliveryVehicle
para o Fleet Engine.
Use o objeto CreateDeliveryVehicleRequest
para definir os atributos do novo veículo de entrega. Observe que qualquer valor especificado no campo Name
é
ignorado de acordo com a orientação da API para IDs especificados pelo usuário.
Use o campo DeliveryVehicleId
para definir o ID do veículo.
Ao criar um DeliveryVehicle
, você tem a opção de especificar estes campos:
- Atributos
- LastLocation
- Tipo
Não defina outros campos. Se você fizer isso, o Fleet Engine 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 campos opcionais, deixe o campo
DeliveryVehicle
sem definição no CreateDeliveryVehicleRequest
.
O exemplo a seguir mostra como usar a 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 usando um ambiente de servidor, faça uma chamada HTTP REST
para CreateDeliveryVehicle
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> é um identificador exclusivo para um veículo de entrega em 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 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 da solicitação POST vazio. O veículo recém-criado extrai um ID do veículo do 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 remessa
É possível criar uma tarefa de retirada de remessa no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para criar uma tarefa de retirada 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.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Para criar uma tarefa de retirada de remessa em um ambiente de servidor, faça uma chamada HTTP REST
para CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> é um identificador exclusivo da tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefa no seu sistema, poderá gerar um identificador universal exclusivo (UUID, na sigla em inglês).
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 state 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 da remessa. taskDuration O tempo esperado, em segundos, 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 afeta 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. O Fleet Engine vai gerar
uma exceção se a solicitação incluir um deliveryVehicleId
atribuído. Atribua
tarefas 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
Crie uma tarefa de entrega de remessa no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar a 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. Ele não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefa no seu sistema, poderá gerar um identificador universal exclusivo (UUID, na sigla em inglês).
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 state 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, para deixar a remessa no local de entrega. Campos opcionais:
Campo Valor targetTimeWindow A janela de tempo em que a tarefa deve ser concluída. Isso não afeta 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. O Fleet Engine vai gerar
uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Atribua
tarefas 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
Criar tarefas em lote
É possível criar um lote de tarefas de um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar a 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 HTTP REST 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>, em que <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 Matriz< CreateTasksRequest
>Campos opcionais:
Campo Valor cabeçalho "DeliveryRequestHeader"
Cada elemento CreateTasksRequest
em requests
precisa passar as mesmas regras de validação que uma solicitação CreateTask
, com exceção de que os campos parent
e header
são opcionais. Se definidos, eles precisam ser idênticos aos
respectivos campos no nível superior BatchCreateTasksRequest
. Consulte
Criar uma tarefa de retirada de remessa e
Criar uma tarefa de entrega de remessa
para conferir as regras de validação específicas de cada uma.
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 que indica indisponibilidade (por exemplo, para motoristas ou reabastecimento de veículos) usando o 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. Você também pode informar um local.
gRPC
O exemplo a seguir mostra como usar a 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 tiver IDs de tarefas no sistema, gere um identificador universal 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 state State.OPEN taskDuration A duração do intervalo em segundos. Campos opcionais:
Campo Valor plannedLocation O local do intervalo, se precisar ser feito em um local específico.
Todos os outros campos da entidade são ignorados para criação. O Fleet Engine vai gerar
uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Atribua
tarefas 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 em um ambiente de servidor usando gRPC ou REST. Uma tarefa de parada programada pode não incluir um ID de acompanhamento.
gRPC
O exemplo a seguir mostra como usar a 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 tarefa no seu sistema, poderá gerar um identificador universal 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 state State.OPEN plannedLocation O local da parada. taskDuration A duração prevista da parada em segundos. Campos opcionais:
- Nenhuma
Todos os outros campos da entidade são ignorados para criação. O Fleet Engine vai gerar
uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Atribua
tarefas 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 a janela de tempo desejada
A janela de tempo desejada é a TimeWindow em que a tarefa precisa ser concluída. Por exemplo, se você comunicar uma janela de tempo de entrega aos destinatários, poderá usar a janela de tempo desejada da tarefa para capturar essa janela e gerar alertas ou analisar o desempenho pós-viagem usando o campo.
A janela de tempo desejada consiste em um horário de início e um horário de término e pode ser definida em qualquer tipo de tarefa. A janela de tempo de destino não afeta o comportamento de definição de trajeto.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir uma janela de horário 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 de 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:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 da visibilidade de rastreamento de tarefas
A visibilidade dos dados na biblioteca Shipment Tracking e dos dados
retornados de uma chamada para GetTaskTrackingInfo
podem ser controladas por tarefa
configurando um
TaskTrackingViewConfig
na tarefa. Consulte
Tarefas ativas do veículo
para mais informações. Isso pode ser feito ao criar ou atualizar a
tarefa. Veja a seguir um exemplo de atualização da tarefa com essa configuração:
gRPC
O exemplo a seguir mostra como usar a biblioteca gRPC do Java 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 de 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 A configuração do rastreamento de tarefas que especifica quais elementos de dados estão visíveis para os usuários finais em quais circunstâncias. Campos opcionais:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 de tarefas do veículo. A ordem de tarefas de um veículo é determinada pela lista de paradas do veículo de entrega, e você pode atribuir uma ou mais tarefas a cada parada. Para mais detalhes, consulte Atualizar a ordem das tarefas.
Para transferir uma remessa de um veículo para outro, feche a tarefa original e a recrie antes de atribuir o novo veículo. Se você atualizar a ordem de uma tarefa que já está atribuída a um veículo diferente, vai receber um erro.
Atualizar a ordem das tarefas
É possível atualizar as tarefas de pedido atribuídas a um veículo no SDK do Driver ou no 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 de um veículo, ela também faz o seguinte:
- Atribui tarefas novas no veículo.
- Fecha todas as tarefas que foram atribuídas anteriormente ao veículo, mas que não estão na ordem atualizada.
Para transferir uma remessa de um veículo para outro, feche a tarefa original e a recrie antes de atribuir o novo veículo. Se você atualizar a ordem de uma tarefa que já está atribuída a um veículo diferente, vai receber um erro.
Você pode atualizar a ordem das tarefas a qualquer momento.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para atualizar a ordem das tarefas do 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 ordenação 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 do veículo de entrega da frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou 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 das tarefas na ordem em que devem ser executadas. A primeira tarefa da lista é executada primeiro. VehicleJourneysegments restante A parada da tarefa i na lista. VehicleJourneySegmentos restante[i].stop.plannedLocation O local planejado para a parada. VehicleJourneySegmentos restante[i].stop.tasks Uma lista de tarefas a serem realizadas nesta parada do veículo. remainingVehicleJourneySegments[i].stop.state State.NEW Campos opcionais:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 motor da frota precisa ser notificado quando um veículo sai de uma parada ou inicia a navegação. Notifique o Fleet Engine a partir do 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 da verdade.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para notificar o Fleet Engine de 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 de que um veículo está a caminho da próxima parada a partir de 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 da frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou 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:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 local do veículo
Se você não estiver usando o SDK do Driver para atualizar a localização do veículo, poderá fazer 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 localização pelo menos uma vez por minuto e no máximo uma vez a cada 5 segundos.
gRPC
O exemplo a seguir mostra como usar a 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 da frota ou do qual você pretende atualizar o local. É o identificador que você especificou 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 O local do veículo. lastLocation.supplementalLocationTime O último carimbo de data/hora conhecido do veículo estava nesse local. lastLocation.supplementalLocationSensor Precisa ser preenchido com CUSTOMER_ autopLIED_LOCATION. Campos opcionais:
Campo Valor lastLocation.supplementalLocationAccuracy Precisão do local informado, 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 em uma parada
O motor da frota precisa ser notificado quando um veículo chega a uma parada. Notifique o Fleet Engine a partir do 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 da verdade.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para notificar o 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 o Fleet Engine sobre a chegada de um veículo em uma parada de 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 da frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou 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 em que você chegou com o estado definido como State.ARRIVED, seguido por uma lista de paradas de veículos restantes com os estados marcados como State.NEW. Campos opcionais:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 faz uma parada
O motor da frota precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada sejam definidas no estado FECHADO. É possível notificar o Fleet Engine pelo SDK do Driver ou por 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 a biblioteca Java gRPC para notificar o Fleet Engine 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 de 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 da frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou 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 que você concluiu não deve mais estar na lista de paradas de veículo restantes. Campos opcionais:
- Nenhuma
Todos os outros campos na entidade são ignorados para a 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 tarefas é imutável. No entanto, é possível modificar o estado, o resultado da tarefa, o horário e o local do resultado da tarefa e os atributos atualizando diretamente a entidade da tarefa. Por exemplo, nos casos em que uma tarefa não foi atribuída a um veículo, você pode encerrá-la atualizando o estado diretamente.
gRPC
Este é um exemplo de atualização de uma tarefa pelo gRPC.
REST
Este é um exemplo de atualização de uma tarefa pelo REST.
Encerrar uma tarefa
Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada onde a tarefa ocorre ou remova-o da lista de paradas de veículos. Para fazer isso, defina a lista das paradas restantes do mesmo modo que ao atualizar a ordem das tarefas de um veículo.
Se uma tarefa ainda não tiver sido atribuída a um veículo e precisar ser fechada, atualize-a para o estado FECHADO. Entretanto, você não pode reabrir uma tarefa FECHADA.
O encerramento de uma tarefa não indica sucesso ou falha. Isso indica que a tarefa não é mais considerada em andamento. Ao rastrear a frota, é importante indicar o resultado real de uma tarefa para que o resultado da entrega seja 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 state State.CLOSED Campos opcionais:
Campo Valor taskOutcome Result.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 é a última localização do veículo, a menos que seja substituído manualmente pelo provedor.
Todos os outros campos na entidade são ignorados para a 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 do resultado
O encerramento de uma tarefa não indica sucesso ou falha, mas sim que a tarefa não é mais considerada em andamento. Para o rastreamento de frota, é importante indicar o resultado real de uma tarefa para que um resultado de entrega possa ser mostrado e que o faturamento dos serviços seja adequado. 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 que eles forem definidos.
As tarefas no estado FECHADO podem ter o resultado definido como SUCCEEDED ou FAILED. O Fleet Engine cobra apenas tarefas de entrega com o estado SUCCEEDED.
Ao marcar o resultado de uma tarefa, o Fleet Engine preenche automaticamente o local de resultado da tarefa com o último local conhecido do veículo. É possível substituir esse comportamento.
gRPC
Você tem a opção de definir o local de resultado da tarefa ao definir o resultado. Isso impede que o Fleet Engine o defina como o padrão da última localização do veículo. Também é possível substituir o local de resultado da tarefa definido pelo Fleet Engine mais tarde. O Fleet Engine nunca substitui um local de resultado de tarefa fornecido por você. Não é possível definir um local de resultado para uma tarefa que não tenha um conjunto de resultados de tarefa. É possível definir o resultado da tarefa e o local dos resultados na mesma solicitação.
O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir um resultado de tarefa como SUCCEEDED e definir o local em que a tarefa foi concluída:
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 Result.SUCCEEDED ou Outcome.FAILED Campos opcionais:
Campo Valor taskOutcomeLocation O local em que a tarefa foi concluída. Se não for definido, o padrão do Fleet Engine será o último local do veículo. taskOutcomeTime O carimbo de data/hora em que a tarefa foi concluída.
Todos os outros campos na entidade são ignorados para a 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 frete é criada, o local planejado não pode ser alterado. Para redirecionar uma remessa, feche a tarefa de remessa sem definir um resultado e crie uma nova tarefa com o local planejado atualizado. Após criar a nova tarefa, atribua-a ao mesmo veículo. Para mais informações, consulte fechar a tarefa de remessa 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 durante todo o dia, modele a transferência das encomendas como uma tarefa de parada programada para o veículo de entrega. Para garantir o rastreamento preciso da localização, só atribua uma tarefa de entrega para uma remessa transferida depois que ela for carregada no veículo de entrega. Para mais informações, consulte parada programada.
Status do envio da loja e outras informações meta
Quando uma tarefa de remessa é concluída, o estado e o resultado da tarefa são registrados nela. No entanto, você pode querer atualizar outras metainformações específicas do envio. Para armazenar outras metainformações que possam ser referenciadas fora do serviço do Fleet Engine, use o "tracking_id" associado à tarefa como uma chave em uma tabela externa.
Para mais informações, consulte O ciclo de uma tarefa.
Procurar um veículo
É possível procurar um veículo no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.
gRPC
O exemplo a seguir mostra como usar a 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 conterá 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 oferece suporte à procura de uma tarefa.
gRPC
O exemplo a seguir mostra como usar a 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 ID 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 "task".
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}"
Pesquisar informações de tarefas de envio pelo ID de rastreamento
É possível procurar informações de tarefas da frota das seguintes maneiras, cada uma com uma finalidade separada:
- por um ID de tarefa: usado por usuários, como operadores de frotas que têm acesso à visualização completa dos dados da tarefa.
- Por um ID de acompanhamento: usado pelo software cliente para fornecer informações limitadas a um usuário final, como quando um pacote é esperado na casa dele.
Esta seção discute a pesquisa de informações da tarefa usando um ID de acompanhamento. 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 de envio fornecidas por um ID de rastreamento estão em conformidade com as regras de visibilidade estabelecidas em Controlar a visibilidade dos locais rastreados.
Use o Fleet Engine para procurar informações de envio pelo ID de rastreamento. O SDK do driver não oferece suporte a pesquisas de informações por ID de acompanhamento. Para fazer isso com o Fleet Engine, você usa um ambiente de servidor ou navegador.
Use o token mais estreito possível para limitar riscos de segurança. Por exemplo, se você usar um token de consumidor de entrega, todas as chamadas da API Fleet Engine Deliveries retornarão somente informações relevantes para esse usuário final, como o remetente ou o recebedor de uma remessa. Todas as outras informações nas respostas são editadas. Para mais informações sobre tokens, consulte Como criar um JSON Web Token (JWT) para autorização.
Pesquisas com Java usando gRPC
O exemplo a seguir mostra como usar a 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 envio em um navegador, faça uma chamada HTTP REST 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>, 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 conterá uma entidade taskTrackingInfo.
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 navegador. O SDK do Driver não permite a listagem de tarefas.
Para listar tarefas, é preciso ter amplo acesso a elas. A listagem de tarefas é destinada apenas a usuários confiáveis. Use o leitor da frota de entrega ou tokens de autenticação de superusuário de entrega ao fazer solicitações de tarefas de lista.
As tarefas listadas têm os seguintes campos editados:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
As tarefas listadas podem ser filtradas pela maioria das propriedades de tarefa. Para saber mais sobre a sintaxe da consulta de filtro, consulte AIP-160. A lista a seguir mostra propriedades de tarefa válidas que podem ser usadas para filtragem:
- atributos
- delivery_vehicle_id
- state
- 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 uma s |
task_duration = 120s |
Tipo enumerado | 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 |
Consulte AIP-160 para ver uma lista completa de operadores de consulta de filtro.
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 tarefas de lista. Se um tamanho de página for especificado, o número de tarefas retornadas não será maior que o tamanho especificado. Se nenhum tamanho de página estiver presente, um padrão razoável será usado. Se o tamanho da página solicitado exceder um valor máximo interno, o máximo interno será usado.
Uma lista de tarefas pode incluir um token para ler a próxima página de resultados. Use o token da página com uma solicitação idêntica à solicitação anterior para recuperar a próxima página de tarefas. Quando o token da página retornado está vazio, não há mais tarefas disponíveis para recuperação.
gRPC
O exemplo a seguir mostra como usar a biblioteca gRPC do Java para listar tarefas para um deliveryVehicleId e um atributo de tarefa. Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que nenhuma tarefa está associada ao 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 de um navegador, faça uma chamada HTTP REST para ListTasks
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Para aplicar um filtro às tarefas listadas, inclua um parâmetro de URL "filtro" 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 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 nenhuma tarefa foi encontrada atendendo 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 SDK do motorista não oferece suporte à listagem de veículos de entrega.
A listagem de veículos de entrega exige amplo acesso aos veículos de entrega e é destinada apenas a usuários confiáveis. Use o leitor da frota de entrega ou os tokens de autenticação de super usuário de entrega ao fazer solicitações de veículos de entrega de listas.
Os veículos de entrega listados têm os seguintes campos editados devido ao impacto deles no tamanho da resposta:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
É possível filtrar a lista de veículos de entrega pela propriedade attributes
. Por
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 ver uma descrição completa da sintaxe da consulta de filtro.
É possível filtrar os veículos de entrega listados por local usando o parâmetro de solicitação viewport
. O parâmetro de solicitação viewport
define janelas de visualização usando duas coordenadas delimitadoras: um par de coordenadas de latitude e longitude high
(nordeste) e low
(sudoeste). As solicitações serão rejeitadas caso contenham uma latitude alta geograficamente menor que uma latitude baixa.
As listas de veículos de entrega são paginadas por padrão usando 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 valor máximo interno, o máximo interno será usado. Os tamanhos de página padrão e máximo 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ó está presente em uma resposta quando mais páginas de veículos de entrega estão disponíveis para recuperação. Para recuperar a próxima página de tarefas, use o token de página com uma solicitação idêntica à solicitação anterior.
gRPC
O exemplo a seguir mostra como usar a biblioteca Java gRPC para listar veículos de entrega em uma região específica com um determinado atributo. Uma resposta bem-sucedida ainda pode estar vazia. Quando isso acontece, significa que nenhum veículo com o atributo especificado já está 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 de um navegador, faça uma chamada HTTP REST para ListDeliveryVehicles
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Para aplicar um filtro às tarefas listadas, inclua um parâmetro de URL "filter" 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 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 nenhum veículo de entrega foi encontrado atendendo à 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
Há duas opções para usar a API Fleet Engine Deliveries para ativar o rastreamento da frota:
Preferencial:use a biblioteca JavaScript Fleet Tracking. A biblioteca permite visualizar a localização de veículos e locais de interesse rastreados no Fleet Engine. Ele contém um componente de mapa JavaScript que é uma substituição simples para um objeto google.maps.Map padrão e componentes de dados para se conectar ao Fleet Engine. Esse componente permite fornecer uma experiência de rastreamento personalizada e animada da frota com seu aplicativo da Web ou para dispositivos móveis.
Implemente o rastreamento da sua própria frota com base na API Fleet Engine Deliveries.
O segredo é procurar tarefas da frota por ID de rastreamento.
Geração de registros
É possível configurar o Fleet Engine para enviar registros de RPC para o Cloud Logging. Para mais informações, consulte Logging.
Papéis e tokens de autorização
Conforme descrito em Gerenciar o ciclo de vida do veículo e da tarefa e as notas de autorização para casos de uso individuais, fazer chamadas para o Fleet Engine exige autenticação com tokens JSON da Web assinados usando credenciais de conta de serviço. As contas de serviço usadas para emitir esses tokens podem ter um ou mais papéis, e cada um deles 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 tiver algum problema.
Resiliência
O Fleet Engine não é considerado uma fonte da verdade. Você é responsável por restaurar o estado do sistema, se necessário, sem depender do Fleet Engine.
Estado perdido no Fleet Engine
Ao trabalhar com o Fleet Engine, implemente os clientes para que o sistema se corrija em caso de falha. Por exemplo, quando o Fleet Engine tenta atualizar um veículo, ele pode responder com um erro indicando que o veículo não existe. O cliente precisa recriar o veículo no novo estado. Embora esse problema raramente ocorra, verifique se o sistema é resiliente o suficiente para resolvê-lo.
No cenário extremamente improvável de uma falha catastrófica do Fleet Engine, talvez seja necessário recriar a maioria ou todos os veículos e tarefas. Se a taxa de criação ficar muito alta, algumas solicitações poderão falhar novamente devido a problemas de cota, já que as verificações de cota estão 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 novas tentativas.
Estado perdido no app do motorista
Se o app do driver falhar, ele precisará recriar o estado atual no SDK do driver. O app precisa tentar recriar tarefas para garantir que elas existam e restaurar os estados atuais. O app também precisa recriar e definir explicitamente a lista de paradas para o SDK do Driver.
Perguntas frequentes
E se um motorista parar em uma tarefa fora de ordem?
Nesse caso, primeiro atualize a ordem das tarefas e prossiga normalmente, marcando a chegada na parada, a conclusão da tarefa e outros detalhes. Se você não fizer isso, o sistema poderá ficar inconsistente, os ETAs poderão ficar incorretos e erros inesperados poderão ser informados.