Primeiros passos com o Fleet Engine

A API Fleet Engine Deliveries permite modelar as atividades da sua frota para a primeira e a última milha de entregas. A API Deliveries é exposta por meio do SDK do driver para Android e iOS e também pode ser usada diretamente por meio de chamadas HTTP REST ou gRPC.

Configuração inicial

A API Fleet Engine Deliveries é configurada por meio do Console do Google Cloud. Para 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 mais detalhes sobre como usar o console, consulte a documentação do console do Google Cloud.

Verificar sua configuração

Depois de criar contas de serviço, verifique se a configuração foi concluída e se é possível criar um veículo de entrega. Ao fazer a verificação neste estágio do fluxo de trabalho, você garante que resolveu problemas comuns de autorização que podem surgir durante a configuração do seu projeto. Siga o guia Como verificar a configuração. Este guia fornece detalhes sobre como usar o utilitário de linha de comando gcloud para testar duas partes principais da configuração: a assinatura do token de autorização e a criação do veículo de entrega de teste.

Como alternativa, você pode usar os exemplos de scripts de autenticação do Fleet Engine para testar sua configuração.

Bibliotecas de cliente

Publicamos bibliotecas de cliente em várias linguagens de programação comuns. Essas bibliotecas oferecem uma experiência de desenvolvedor melhor em relação ao REST ou gRPC bruto. Para ver instruções sobre como receber bibliotecas de cliente para seu aplicativo do servidor, consulte Bibliotecas de cliente.

Os exemplos em Java nesta documentação pressupõem familiaridade com o gRPC.

Estruturas de dados

A API 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 da remessa.

Além disso, você pode usar tarefas para modelar as pausas 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, elas também podem transportar uma remessa diretamente do local de retirada para o local de entrega.

Você pode usar o SDK do driver para criar um objeto DeliveryVehicle no Fleet Engine e enviar atualizações de localização para o rastreamento da remessa e da frota.

Observação: os objetos DeliveryVehicle podem ter no máximo 500 tarefas e 300 segmentos de jornada de veículo restantes atribuídos.

Tarefas

Cada veículo tem tarefas atribuídas. Isso pode incluir tarefas de retirada ou entrega, intervalos necessários para motoristas ou paradas programadas em caixas de depósito ou clientes. Cada tarefa precisa ter um ID exclusivo, mas pode compartilhar o mesmo ID de acompanhamento. As tarefas e a ordem em que estão programadas são usadas para calcular as janelas de HEC de cada tarefa.

Use o gerenciador de tarefas do SDK do driver para criar tarefas no Fleet Engine.

Tarefas de envio

As tarefas de envio estão relacionadas à coleta ou entrega do item. Você deve especificar um número de rastreamento ou ID ao criar uma tarefa de remessa. Também é necessário especificar um tempo de permanência para contabilizar o tempo adicional para concluir a tarefa, procurar estacionamento ou caminhar até o local de transferência.

• Crie uma tarefa de retirada para retirar uma remessa, especificando o local de retirada e o número ou ID de rastreamento.
• Crie uma tarefa de entrega para entregar uma remessa, especificando o local de entrega e o número ou ID de rastreamento.

Tarefas de indisponibilidade

Crie uma tarefa de indisponibilidade para um período em que o veículo não estará disponível para retiradas ou entregas. Pode ser uma pausa para reabastecer o veículo ou um descanso do motorista. Especifique a duração da pausa ao criar a tarefa. As pausas não precisam ser feitas em um local específico, mas especificar um local fornece janelas de HEC mais precisas ao longo do dia.

Durante uma tarefa de indisponibilidade, nenhuma informação de localização é compartilhada com o usuário final. Por exemplo, a localização do veículo de entrega fica oculta dos gerentes de frota usando a biblioteca Fleet Tracking.

Tarefas de parada programada

Crie tarefas de paradas programadas para modelar as paradas que serão feitas por um veículo de entrega. Por exemplo, é possível criar 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.

Observação :as informações de localização do veículo não são compartilhadas durante o rastreamento de envios para tarefas programadas e de indisponibilidade. No entanto, está disponível para o rastreamento de frotas.

É possível ver os campos específicos contidos em cada estrutura de dados na documentação de referência da API para DeliveryVehicle (gRPC, REST) e Task (gRPC, REST).

Diretrizes do ID da tarefa

Os IDs de tarefas precisam ser exclusivos e não podem expor nenhuma informação de identificação pessoal (PII) ou dados de texto não criptografado. Os IDs de tarefas também precisam estar em conformidade com os seguintes requisitos de formato:

• Os IDs precisam ser strings Unicode válidas.
• Os IDs precisam ter, no máximo, 64 caracteres.
• Os IDs serão normalizados de acordo com o Formulário de normalização Unicode C.
• Os códigos não podem conter nenhum dos seguintes caracteres ASCII: "/", ":", "\", "?" ou "#".

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 inválidos:

IDs de tarefas inválidas	Motivo
31/08/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 requisitos de PII.
4R0oXLToF”112 Summer Dr. East Hartford, CT06118”577b484da26f8a	Viola PII e requisitos de caracteres: espaço em branco, vírgulas e aspas. Com mais de 64 caracteres.

Vida útil de um veículo

O objeto DeliveryVehicle representa um veículo de entrega de primeira ou última milha. Você cria 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.

O ID de cada veículo precisa ser exclusivo. Eles não podem ser reutilizados em outro veículo, a menos que não haja tarefas ativas para ele.

Verifique se há um erro NOT_FOUND ao fazer uma chamada para UpdateDeliveryVehicle e, em seguida, se necessário, chame CreateDeliveryVehicle para criar um novo veículo. Um objeto DeliveryVehicle que não foi atualizado usando UpdateDeliveryVehicle é excluído automaticamente após sete dias. Chamar CreateDeliveryVehicle com um par de ID do projeto/ID do veículo que já existe gera um erro.

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. DeliveryVehicleAttributes não afetam o comportamento de roteamento do Fleet Engine.

Não inclua informações sensíveis ou de identificação pessoal nos atributos, porque esse campo pode ficar visível para os usuários.

O ciclo de uma tarefa

As tarefas no Fleet Engine podem ser criadas, atualizadas e interrogadas usando as interfaces REST ou gRPC 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. Novas tarefas são criadas no estado OPEN, o que indica que:

• A tarefa ainda não foi atribuída a um veículo de entrega.
• O veículo de entrega ainda não passou da parada atribuída à tarefa.

Uma tarefa só pode ser atribuída a um veículo no estado OPEN.

Uma tarefa pode ser cancelada removendo-a da lista de paradas de veículos. Seu status é definido automaticamente como FECHADO.

Quando o veículo da tarefa concluir a parada, atualize o campo de resultado da tarefa como SUCCEEDED ou FAILED e especifique o carimbo de data/hora do evento. O resultado da tarefa pode ser definido a qualquer momento antes ou depois da conclusão da tarefa, mas pode ser definido apenas uma vez.

Então, a biblioteca JavaScript Fleet Tracking pode indicar o resultado da tarefa. O status da tarefa é definido automaticamente como FECHADO. Para saber mais, consulte Monitorar sua frota com a biblioteca JavaScript Fleet Tracking.

Assim como os veículos, as tarefas que não foram atualizadas após sete dias são excluídas, e a tentativa de criar uma tarefa com um ID já existente retorna 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 da tarefa por mais de sete dias, implemente essa funcionalidade por conta própria.

Atributos da tarefa

A entidade Task contém um campo repetido de TaskAttribute, que pode ter valor de um dos três tipos: string, número e booleano. A API ListTasks inclui um campo filter que pode limitar as entidades Task retornadas àquelas com os atributos especificados. TaskAttributes não afetam o comportamento de roteamento do Fleet Engine.

Não inclua informações sensíveis ou de identificação pessoal nos atributos, porque esse campo pode ficar visível para os usuários.

Como gerenciar o ciclo de vida de veículos e tarefas

Para gerenciar ciclos de vida de veículos e tarefas no sistema, use a API Fleet Engine Deliveries para criar, atualizar e rastrear seus veículos e as tarefas associadas a eles. Seu sistema interno atua como a fonte confiável dos dados que a API Fleet Engine Deliveries aumenta em seu nome.

Ao mesmo tempo, o aplicativo do driver se comunica diretamente com o Fleet Engine para atualizar as informações de local e rota do dispositivo. Esse modelo permite que o Fleet Engine gerencie com eficiência a localização em tempo real e envie diretamente para a biblioteca de rastreamento, que pode ser usada para os consumidores que precisam de atualizações de status do pedido.

Por exemplo, suponha que você tenha o seguinte cenário:

• Um motorista se aproxima de uma parada de entrega e o Fleet Engine envia a localização do dispositivo para a biblioteca de rastreamento, que seu aplicativo de consumidor usa para alertar o consumidor sobre a proximidade do pacote.
• Depois que o motorista conclui o envio, ele clica no botão "Envio entregue" no aplicativo do motorista.
• Isso envia as informações para o sistema de back-end, que executa as etapas necessárias de validação e verificação de negócios.
• Seu sistema confirma que a tarefa foi CONCLUÍDA e atualiza o Fleet Engine usando a API Deliveries.

O diagrama a seguir ilustra esses processos em um nível genérico. Ele também mostra a relação padrão entre seu sistema, o cliente e o Fleet Engine.

Gerenciamento de tokens do cliente

Todas as atualizações de local originadas do aplicativo do driver e enviadas diretamente ao Fleet Engine exigem tokens de autorização. A abordagem recomendada para gerenciar atualizações do cliente para o Fleet Engine é fornecer ao aplicativo do driver um token de escopo limitado para que ele só possa atualizar a localização do dispositivo no Fleet Engine. Para esse tipo de token, use um papel de conta de serviço conhecido como Usuário de motorista não confiável de entrega do Fleet Engine. Isso 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 Motorista não confiável, como para algumas atualizações de tarefas, use o papel de Motorista confiável. Para informações sobre um modelo que usa a função Motorista confiável, consulte Modelo de motorista confiável.

Para mais informações sobre os usos de papéis de driver não confiáveis e confiáveis, consulte Configuração do projeto do Cloud.

Como simular um dia de trabalho

A tabela a seguir descreve como pode ser um dia de trabalho para motoristas de primeira ou última milha em uma empresa de entrega e logística. Sua empresa pode variar nos detalhes, mas você pode ver como é possível modelar um dia de trabalho.

Tempo	Atividade	Modelagem
Até 24 horas após o início	O agente atribui remessas aos veículos de entrega ou rotas.	As tarefas de entregas, retiradas, quebras de remessa etc. podem ser criadas com antecedência no Fleet Engine. Por exemplo, é possível criar uma tarefa de retirada de envio, tarefa de entrega de envio, indisponibilidade programada ou parada programada. As tarefas precisam ser atribuídas a um veículo quando o conjunto de pacotes de entrega e a ordem em que são entregues são finalizados.
Início do dia	O motorista começa o dia no depósito fazendo login no app Motorista.	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, escaneando as remessas.	Se as tarefas de entrega de remessas não tiverem sido criadas antes da hora, crie tarefas de entrega no momento da verificação.
	O motorista confirma a ordem das tarefas a serem realizadas.	Se elas não foram criadas com antecedência, crie tarefas de retirada de frete, indisponibilidade programada e paradas programadas.
	O motorista sai do depósito e se compromete com o próximo número de tarefas a serem realizadas.	Atribua todas as tarefas ou um subconjunto delas ao veículo confirmando a ordem de conclusão.
	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 o envio, feche a tarefa de entrega e, opcionalmente, armazene o status da remessa e outras informações meta. Depois de concluir todas as tarefas na parada e antes de começar a dirigir para a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo está avançando até a próxima parada.
	O motorista encontra um veículo alimentador para transferir outras remessas 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 atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
	O motorista recebe uma notificação de um pedido de retirada.	Depois de aceitar o pedido de retirada, crie uma tarefa de retirada de frete. Em seguida, atualize a ordem de execução da tarefa atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
Pico	O motorista faz o intervalo 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 que chega em uma parada, o veículo conclui uma parada e o veículo segue para a próxima parada. Caso contrário, você não precisa fazer mais nada até o fim do intervalo. Remova a tarefa confirmando as próximas e as restantes e atualizando a ordem das tarefas.
	O motorista retira uma remessa.	Isso é modelado como um ponto de entrega. Realize ações relacionadas a um veículo chegando a uma parada e fecha uma tarefa e, como opção, armazenar o status da remessa e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a se deslocar até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo se desloca 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 tiver que ser entregue em outro local no mesmo trajeto do motorista nesse dia, recomendamos modelar essa tarefa de entrega como qualquer outra no trajeto. Se o motorista estiver trazendo a retirada de volta para o depósito, recomendamos que você crie 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.	Esse local é modelado como qualquer outro ponto de embarque. Realize ações relacionadas a um veículo chegando a uma parada e ao fechar uma tarefa. Depois de concluir todas as tarefas na parada 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 percorre até a próxima parada.
	O motorista recebe uma notificação de que uma remessa está sendo desviada para um local alternativo.	Defina o status da tarefa de entrega da remessa original como CONCLUÍDA e crie uma nova tarefa de entrega para o novo local de entrega. Para mais informações, consulte Redirecionar uma remessa.
	O motorista tentou entregar um pacote, mas não conseguiu.	Isso é 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 chegando a uma parada. Depois de não entregar o envio, feche a tarefa e, como opção, armazene o status da remessa e outras informações meta. Depois de concluir todas as tarefas na parada e antes de começar a se deslocar até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo se desloca 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 COMPLETED.
	O motorista foi notificado para entregar uma 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. 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, armazene o status da remessa e outras informações meta. Depois de concluir todas as tarefas na parada e antes de começar a se deslocar até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo se desloca até a próxima parada.
Fim do dia	O motorista retorna ao depósito.	Se o motorista retornar ao depósito com as remessas retiradas durante o trajeto, você também precisará criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. Para 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. Assim, os motoristas poderão conferir a rota de volta até o depósito, além de informar o horário previsto de chegada.

Sobre as atualizações de localização

As atualizações de local são enviadas ao Fleet Engine assim que um veículo de entrega sai de uma parada (incluindo o depósito) até que ele chegue na próxima parada. Como esses eventos não são detectados automaticamente, é preciso marcá-los de maneira programática. Use bibliotecas que detectam mudanças no meio de transporte para acionar o envio das notificações necessárias para o Fleet Engine.

As atualizações de localização precisam ser suspensas quando o motorista não estiver dirigindo, porque a qualidade dos sinais de localização piora drasticamente quando alguém está dentro de um prédio.

A frequência de atualização de local pode ser definida no SDK do driver. O padrão envia atualizações a cada 10 segundos.

Paradas de veículos e locais de entrega

Uma parada de veículo é quando um veículo de entrega conclui uma tarefa de remessa ou alguma outra. Ele é um ponto de acesso, como uma base de carregamento, ou um local posicionado na via.

O local de entrega é onde a remessa é 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 para 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 de veículo até o local dentro do shopping onde a loja está localizada. Esse é 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 restantes para tarefas de remessa é informado ao usuário para ajudar a visualizar o progresso do envio.

Por exemplo, se um motorista estiver fazendo muitas entregas para um único prédio comercial, 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 de veículo, a experiência de rastreamento de frete será menos útil para os usuários, já que o rastreamento só vai 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 dará ao usuário muito tempo para acompanhar o progresso da entrega.

Como usar SDKs para dispositivos móveis

Antes de fazer qualquer chamada para o SDK do driver, inicialize-o.

Como inicializar a API Delivery Driver

Antes de inicializar a API Delivery Driver no SDK Driver, inicialize o SDK do Navigation. Depois, 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));
     }
   });

Observação:o SDK do driver contém APIs para várias indústrias, incluindo entregas. Para reduzir o tamanho geral do binário, use o ProGuard ou alguma outra ferramenta de otimização para remover o código não utilizado.

Casos de uso

Esta seção descreve como usar a API Deliveries para modelar casos de uso comuns.

Identificadores de entidade exclusivos

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 confira se o identificador não contém informações de identificação pessoal (PII), como o número de telefone do motorista.

Criar um veículo

Você pode criar um veículo no SDK do motorista ou no ambiente do servidor.

gRPC

Para criar um veículo novo, faça uma chamada CreateDeliveryVehicle para o Fleet Engine. Use o objeto CreateDeliveryVehicleRequest para definir os atributos do novo veículo de entrega. Qualquer valor especificado no campo Name será ignorado de acordo com as orientações da API para IDs especificados pelo usuário. Use o campo DeliveryVehicleId para definir o ID do veículo.

Ao criar um DeliveryVehicle, é possível especificar dois campos:

• Atributos
• Último local

Nenhum outro campo pode ser definido. Caso contrário, o Fleet Engine retornará um erro, porque esses campos são somente leitura ou só podem ser atualizados por chamadas UpdateDeliveryVehicle.

Para criar um veículo sem definir campos opcionais, deixe o campo DeliveryVehicle indefinido em 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 REST HTTP para CreateDeliveryVehicle:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id> é um identificador exclusivo dos veículos de entrega da sua frota.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é um token criado por uma fábrica de tokens do Fleet Engine.

O corpo do POST representa a entidade DeliveryVehicle a ser criada. É possível especificar os seguintes campos opcionais:

• atributos
• lastLocation

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. Nenhum outro campo pode ser definido. Caso contrário, o Fleet Engine retornará um erro porque esses campos são somente leitura ou só podem ser atualizados por chamadas UpdateDeliveryVehicle.

Para criar um veículo sem definir campos, deixe o corpo da solicitação POST vazio. O veículo recém-criado terá um ID de veículo extraído 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 frete

Você pode criar uma tarefa de retirada de frete no SDK do motorista ou no ambiente do servidor.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para criar uma tarefa de retirada de frete:

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para criar uma tarefa de retirada de frete em um ambiente de servidor, faça uma chamada REST HTTP para "CreateTask":

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> é um identificador exclusivo para a tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tem IDs de tarefa no seu sistema, é possível 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  digitar	Tipo.PICKUP
  estado oculto final	State.OPEN
  trackingId	O número ou identificador que você está usando para rastrear um envio.
  PlanningLocation	O local em que a tarefa será concluída. Neste caso, o local de retirada da remessa.
  taskDuration	O tempo esperado, em segundos, que levará 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. No momento, isso não afeta o comportamento de roteamento.
  atributos	Uma lista de atributos personalizados da tarefa. Cada atributo precisa ter uma chave exclusiva.

Todos os outros campos na entidade são ignorados para criação. O Fleet Engine gerará uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequests. Para saber mais, consulte Atribuir tarefas a um veículo.

Comando curl de exemplo:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Criar uma tarefa de entrega de frete

Você pode criar uma tarefa de entrega de frete no SDK do driver ou no ambiente do servidor.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para criar uma tarefa de entrega de envio:

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 a partir de um ambiente de servidor, faça uma chamada REST HTTP para "CreateTask":

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>

<id> é um identificador exclusivo para a tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tem IDs de tarefa no seu sistema, é possível 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  digitar	Type.ENTREGA
  estado oculto final	State.OPEN
  trackingId	O número ou identificador que você está usando para rastrear um envio.
  PlanningLocation	O local em que a tarefa será concluída. Neste caso, o local de entrega da remessa.
  taskDuration	O tempo esperado, em segundos, que levará 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. No momento, isso não afeta o comportamento de roteamento.
  atributos	Uma lista de atributos personalizados da tarefa. Cada atributo precisa ter uma chave exclusiva.

Todos os outros campos na entidade são ignorados para criação. O Fleet Engine gerará uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequests. Para saber mais, consulte Atribuir tarefas a um veículo.

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 no ambiente do servidor.

Este produto ou recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. Todos os itens em pré-GA são cobertos pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para criar duas tarefas, uma para uma 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 no ambiente do 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 criado 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 transmitir as mesmas regras de validação que uma solicitação CreateTask, com a 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 coleta de frete e criar uma tarefa de entrega de remessa para conferir regras de validação específicas para 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 reparos ou reabastecimento de veículos) usando o SDK do motorista ou no ambiente do servidor. Uma tarefa de indisponibilidade programada não pode incluir um ID de acompanhamento. Também é possível informar um local.

gRPC

O exemplo a seguir mostra como usar 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 a partir de 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 para a tarefa. Se você não tem IDs de tarefa no seu sistema, é possível 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  digitar	Tipo.UNAVAILABLE
  estado oculto final	State.OPEN
  taskDuration	A duração da pausa em segundos.

• Campos opcionais:

  Campo	Valor
  PlanningLocation	O local do intervalo, se necessário.

Todos os outros campos na entidade são ignorados para criação. O Fleet Engine gerará uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequests. Para saber mais, consulte Atribuir tarefas a um veículo.

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

Você pode criar uma tarefa de parada programada no SDK do driver ou no ambiente do servidor. 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 para a tarefa. Se você não tem IDs de tarefa no seu sistema, é possível 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  digitar	Tipo.scheduleD_STOP
  estado oculto final	State.OPEN
  PlanningLocation	O local da parada.
  taskDuration	A duração prevista da parada em segundos.

• Campos opcionais:

  • Nenhum

Todos os outros campos na entidade são ignorados para criação. O Fleet Engine gerará uma exceção se a solicitação incluir um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequests. Para saber mais, consulte Atribuir tarefas a um veículo.

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 de destino é a Janela de tempo 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 de destino 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 de término e pode ser definida em qualquer tipo de tarefa. No momento, a janela de tempo de destino não afeta o comportamento de roteamento.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir uma janela de tempo 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)
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para definir uma janela de tempo da tarefa usando HTTP, chame UpdateTask:

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow

<id> é um identificador exclusivo para a tarefa.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é um token criado 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. No momento, isso não afeta o comportamento de roteamento

• Campos opcionais:

  • Nenhum

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 conferir 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 para a tarefa.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é um token criado 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 são visíveis para os usuários finais em quais circunstâncias.

• Campos opcionais:

  • Nenhum

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

As tarefas são atribuídas a um veículo de entrega com a atualização da ordem das tarefas para o veículo. A ordem das tarefas de um veículo é determinada pela lista de paradas do veículo de entrega. É possível atribuir uma ou mais tarefas a cada parada.

A atualização da ordem de uma tarefa que foi atribuída anteriormente a um veículo diferente gera um erro.

Para mudar uma remessa de um veículo para outro, feche a tarefa original e recrie-a antes de atribuir o novo veículo.

Atualizar a ordem das tarefas

É possível atualizar a ordem de execução das tarefas atribuídas a um veículo no SDK do motorista ou no ambiente do servidor. Os dois métodos não devem ser misturados para evitar disputas.

A atualização da ordem de tarefas também atribui tarefas a um veículo caso elas não tenham sido atribuídas anteriormente a um veículo e encerra tarefas que foram atribuídas anteriormente a um veículo e não incluídas no pedido atualizado. Atribuir uma tarefa a um veículo diferente, caso ela já tenha sido atribuída a outro veículo gera um erro. Feche a tarefa existente primeiro e, em seguida, crie uma nova tarefa antes de atribuí-la ao novo veículo.

A ordem das tarefas pode ser atualizada a qualquer momento.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para atualizar a ordem de tarefas para o veículo:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para atualizar a ordem da tarefa de um veículo a partir de 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 para um 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

• Campos obrigatórios:

  Campo	Valor
  Segmentos restantesDeJornada de Veículo	Uma lista de segmentos da jornada para tarefas na ordem em que devem ser executadas. A primeira tarefa da lista é executada primeiro.
  restantesVehicleJourneySegments[i].stop	A parada da tarefa i na lista.
  restantesVehicleJourneySegments[i].stop.plannedLocation	O local planejado para a parada.
  restantesVehicleJourneySegments[i].stop.tasks	Uma lista de tarefas a serem realizadas nesta parada do veículo.
  restantesVehicleJourneySegments[i].stop.state	Estado.NOVO

• Campos opcionais:

  • Nenhum

Todos os outros campos na entidade são ignorados para a atualização.

Comando curl de exemplo:

Observação: isso vai substituir qualquer remainingVehicleJourneySegments definido atualmente no veículo de entrega.

# 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 partir de uma parada ou iniciar a navegação. Você pode notificar o Fleet Engine pelo SDK do driver ou pelo ambiente do servidor. Não combine 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 de que um veículo está se aproximando 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á se aproximando da próxima parada de 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 para o qual 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

• Campo obrigatório:

  Campo	Valor
  Segmentos restantesDeJornada de Veículo	Lista de paradas de veículos restantes com os estados marcados como State.NEW. O estado da primeira parada da lista precisa estar marcado como State.ENROUTE.

• Campos opcionais:

  • Nenhum

Todos os outros campos da entidade são ignorados para a notificação.

Comando curl de exemplo:

Observação: isso vai substituir qualquer remainingVehicleJourneySegments definido atualmente no veículo de entrega.

# 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

O veículo chega a uma parada

O motor da frota precisa ser notificado quando um veículo chegar a uma parada. Você pode notificar o Fleet Engine pelo SDK do driver ou pelo ambiente do servidor. Não combine 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 de 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 a uma parada de 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 para o qual 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

• Campos obrigatórios:

  Campo	Valor
  Segmentos restantesDeJornada de Veículo	A parada em que você chegou com o estado definido como State.ARRIVED, seguida por uma lista de paradas de veículos restantes com os estados marcados como State.NEW.

• Campos opcionais:

  • Nenhum

Todos os outros campos na entidade são ignorados para a atualização.

Comando curl de exemplo:

Observação: isso vai substituir qualquer remainingVehicleJourneySegments definido atualmente no veículo de entrega.

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

O veículo conclui uma parada

O motor da frota precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada sejam definidas para o estado FECHADO. É possível notificar o Fleet Engine pelo SDK do driver ou pelo ambiente do servidor. Os dois métodos não devem ser misturados 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 para o qual 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade DeliveryVehicle:

• Campos obrigatórios:

  Campo	Valor
  segmentos_jornada_restantes_vehicle	A parada que você concluiu não deve mais estar na lista de paradas de veículo restantes.

• Campos opcionais:

  • Nenhum

Todos os outros campos na entidade são ignorados para a atualização.

Comando curl de exemplo:

Observação: isso vai substituir qualquer remainingVehicleJourneySegments definido atualmente no veículo de entrega.

# 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}",
            "taskDuration": "120s"
          }
        ]
      }
    }
  ]
}
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, é possível 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 usando REST.

Fechar uma tarefa

Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada onde a tarefa ocorre ou remova a tarefa da lista de paradas de veículo. Para fazer isso, defina a lista com as paradas restantes do veículo da mesma forma que ocorre 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. No entanto, 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. Para o rastreamento de frotas, é importante indicar o resultado real de uma tarefa para que um resultado de entrega possa ser mostrado.

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // It's only possible to directly CLOSE a
  .build();                    // task which 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 para a tarefa.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é um token criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  estado oculto final	Estado.FECHADO

• Campos opcionais:

  Campo	Valor
  Resultado	Resultado.SUCCEEDED ou Resultado.FAILED
  TaskOutcomeTime	A hora em que a tarefa foi concluída.
  TaskOutcomeLocation	O local em que a tarefa foi concluída. O Fleet Engine usará como padrão 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 que a tarefa não é mais considerada em andamento. No rastreamento da frota, é importante indicar o resultado real de uma tarefa para que um resultado de entrega possa ser mostrado e haja o faturamento adequado dos serviços. Depois de definido, não é possível mudar o resultado da tarefa. É possível modificar o horário e o local do resultado da tarefa depois de 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 do resultado com a última localização conhecida do veículo. É possível modificar esse comportamento.

gRPC

Você tem a opção de definir o local do resultado da tarefa durante a definição do resultado. Isso impedirá que o Fleet Engine o defina como o padrão do último local do veículo. Também é possível substituir o local de resultado da tarefa definido pelo Fleet Engine mais tarde. O Fleet Engine nunca substituirá 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 e o local do resultado da tarefa 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 para a tarefa.

O cabeçalho da solicitação precisa conter um campo Authorization com o valor Bearer <token>, em que <token> é um token criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa conter uma entidade Task:

• Campos obrigatórios:

  Campo	Valor
  Resultado	Resultado.SUCCEEDED ou Resultado.FAILED
  TaskOutcomeTime	O carimbo de data/hora de quando o resultado da tarefa foi definido (do provedor). Esse é o momento em que a tarefa foi concluída.

• Campos opcionais:

  Campo	Valor
  TaskOutcomeLocation	O local em que a tarefa foi concluída. O Fleet Engine usará como padrão 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=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Redirecionar uma remessa

Depois que uma tarefa de remessa é criada, o local planejado não pode ser alterado. Para redirecionar um envio, feche a tarefa de envio sem definir um resultado e crie uma nova tarefa com o local planejado atualizado. Depois de criar a nova tarefa, atribua-a ao mesmo veículo. Para mais informações, consulte Fechar a tarefa de frete e atribuir a tarefa.

Usar alimentador e veículos de entrega

Se você usa veículos alimentadores para transportar remessas para veículos de entrega ao longo do dia, modele a transferência de remessas 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 a uma remessa transferida depois que ela for carregada no veículo de entrega. Para mais informações, consulte parada programada.

Armazenar status de envio e outras informações meta

Quando uma tarefa de remessa é concluída, o estado e o resultado dela são registrados nela. No entanto, é possível 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

Você pode procurar um veículo no SDK do motorista ou no ambiente do servidor.

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 REST HTTP para "GetVehicle":

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>

<id> é um identificador exclusivo para a 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 criado 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 procurar uma tarefa em um ambiente de servidor. O SDK do driver não oferece suporte à pesquisa 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 para a 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 criado por uma fábrica de tokens do Fleet Engine.

O corpo da solicitação precisa estar vazio.

Se a pesquisa for bem-sucedida, o corpo da resposta conterá uma entidade de tarefa.

Comando curl de exemplo:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Pesquisar informações de tarefas de frete pelo ID de acompanhamento

Este produto ou recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. Todos os itens em pré-GA são cobertos pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

É possível procurar informações sobre tarefas de frete das maneiras a seguir, 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 chegará à casa dele.

Esta seção aborda a pesquisa de informações da tarefa usando um ID de acompanhamento. Se você quiser procurar uma tarefa pelo ID, acesse Procurar uma tarefa.

Para procurar informações usando um ID de acompanhamento, você pode usar uma das seguintes opções:

• Pesquisas com Java usando gRPC
• Pesquisas usando HTTP

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 de locais rastreados.

• Use o Fleet Engine para procurar informações de envio pelo ID de rastreamento. O SDK do driver não é compatível com pesquisas de informações por ID de acompanhamento. Para fazer isso com o Fleet Engine, você usará um ambiente de servidor ou de navegador.

• Usar o token mais restrito possível para limitar os riscos à segurança. Por exemplo, se você usar um token de consumidor de entrega, todas as chamadas da API Fleet Engine Deliveries retornarão apenas informações relevantes para esse usuário final, como o remetente ou o receptor de uma remessa. Todas as outras informações nas respostas serã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 acompanhamento.

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 oferece suporte à listagem de tarefas.

Para listar tarefas, é preciso ter acesso amplo a elas. A listagem de tarefas é destinada apenas a usuários confiáveis. Use o leitor da frota de entrega ou os 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 tarefas. Para a sintaxe de consulta de filtro, consulte AIP-160. A lista a seguir mostra propriedades de tarefa válidas que podem ser usadas para filtragem:

• atributos
• id_vehicle_entrega
• estado oculto final
• local_planejado
• Task_duration
• Task_outcome
• task_outcome_location
• task_outcome_location_source
• Task_outcome_time
• id_de_rastreamento
• digitar

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 (link em inglês)	task_outcome_time = 2022-03-01T11:30:00-08:00
Duração	Número de segundos seguidos por um "s"	task_duration = 120s
Enumeração	String	state = CLOSED AND type = PICKUP
Local	point.latitude e point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

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 nas 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 à anterior para recuperar a próxima página de tarefas. Quando o token de página retornado está vazio, não há mais tarefas disponíveis para recuperação.

Observação :filtrar os atributos de tarefas pode fazer com que a latência de recuperação aumente significativamente e precisa ser usado com cautela.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para listar tarefas de 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 em 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 criado por uma fábrica de tokens do Fleet Engine.

Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir dados com a estrutura a seguir:

// JSON representation
{
  "tasks": [
    {
      object (Task)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que não foram encontradas tarefas que atendam 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 os veículos de entrega em um ambiente de servidor ou navegador. O SDK do motorista não é compatível com a listagem de veículos de entrega.

A listagem de veículos de entrega solicita 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 superusuá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 no tamanho da resposta:

• CurrentRouteSegment
• Segmentos restantes do Journey do veículo

É possível filtrar os veículos de entrega da lista pela propriedade do 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 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 de 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: uma latitude/longitude high (nordeste) e low (sudoeste). As solicitações serão rejeitadas se contiverem uma latitude alta geograficamente menor que uma latitude baixa.

Observação :se você não especificar nenhuma consulta de filtro ou janela de visualização, a resposta vai incluir todos os veículos de entrega.

As listas de veículos de exibição 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á somente 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 com uma solicitação idêntica à 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 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 em 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 criado por uma fábrica de tokens do Fleet Engine.

Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir dados com a estrutura a seguir:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Uma resposta bem-sucedida ainda pode estar vazia. Quando isso acontece, significa que não foram encontrados veículos de entrega que atendam à consulta de filtro e à janela de visualização especificadas.

Comando curl de exemplo:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

Rastreamento de frotas

Você tem duas opções para usar a API Fleet Engine Deliveries para ativar o rastreamento da frota:

• Preferencial:use 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. Assim, é possível oferecer uma experiência de rastreamento de frota animada e personalizável no seu aplicativo da Web ou para dispositivos móveis.

• Implemente o rastreamento da sua frota com base na API Fleet Engine Deliveries.

Geração de registros

É possível ativar uma opção para permitir que o Fleet Engine envie registros de RPC para o Cloud Logging. Para mais informações, consulte Logging.

Papéis e tokens de autorização

Conforme descrito em Como integrar a API Deliveries e as notas de autorização para os casos de uso individuais, fazer chamadas para o Fleet Engine requer autenticação com tokens JSON da Web assinados usando as credenciais da conta de serviço. As contas de serviço usadas para cunhar 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

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. Em seguida, o cliente recria o veículo no novo estado. Isso raramente ocorre. O sistema precisa ser resiliente caso isso aconteça.

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 verificações de cota são feitas 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 do SDK do motorista.

Essas restaurações precisam ser feitas de maneira autônoma, sem depender de informações do Fleet Engine, com exceção dos erros que indicam se e quando uma entidade já existe no banco de dados. Se uma entidade já existir, esse erro poderá ser absorvido, e a entidade poderá ser atualizada usando o ID.

Perguntas frequentes

E se um motorista para uma tarefa fora de ordem?

Nesse caso, primeiro atualize a ordem das tarefas e, em seguida, prossiga normalmente, marcando a chegada à parada, a conclusão da tarefa etc. Caso contrário, o sistema pode ficar inconsistente. Os ETAs podem ficar incorretos, e erros inesperados podem ser reportados.