Comece a usar o Fleet Engine para rastreamento de envios

Modele as atividades da frota para a primeira e última milha de entregas com a API Fleet Engine Deliveries. É possível usar essa API com o SDK do Driver para Android e iOS ou diretamente usando chamadas HTTP REST ou gRPC.

Configuração inicial

Configure a API Fleet Engine Deliveries no Console do Google Cloud.

• Para informações sobre as etapas a serem seguidas no console e como criar um JSON Web Token para autorização, consulte Autenticação e autorização.

• Para detalhes sobre como usar o console, consulte a documentação do Console do Google Cloud.

Verificar sua configuração

Depois de criar as contas de serviço, verifique se a configuração foi concluída e se você pode criar um veículo de entrega. Verificar sua configuração imediatamente garante que você resolveu problemas comuns de autorização que podem surgir durante a configuração do projeto. Há duas maneiras de verificar a configuração:

• Teste duas partes principais da configuração: assinatura do token de autorização e criação do veículo de entrega de teste com o utilitário de linha de comando gcloud. Para mais detalhes, consulte o guia Como verificar a configuração.

• Teste sua configuração com os scripts de amostra de autenticação do Fleet Engine.

Bibliotecas de cliente

Para uma melhor experiência de desenvolvedor com gRPC ou REST bruto, use as bibliotecas de cliente em várias linguagens de programação comuns. Para instruções sobre como receber bibliotecas de cliente para seu aplicativo de servidor, consulte Bibliotecas de cliente.

Os exemplos de Java nesta documentação pressupõem que você esteja familiarizado com gRPC.

Estruturas de dados

A API Fleet Engine Deliveries usa duas estruturas de dados para modelar a coleta e a entrega das remessas:

• O veículo de entrega usado para transportar a remessa.
• As tarefas de retirada e entrega de remessas.

Também é possível usar tarefas para modelar intervalos de motoristas e paradas programadas ao longo do dia.

Veículos de entrega

Os veículos de entrega transportam remessas de um depósito para um local de entrega e de um local de retirada para o depósito. Em alguns casos, eles também podem transportar uma remessa diretamente do local de retirada para o local de entrega.

Use o SDK do Driver para criar um objeto DeliveryVehicle no Fleet Engine e enviar atualizações de localização para rastreamento de frotas e remessas.

Tarefas

Para as ações que um veículo realiza durante o dia, você atribui tarefas de acordo com o tipo de ação:

• Para retiradas e entregas, atribua Tarefas de envio.
• Quando os motoristas não estiverem disponíveis, como nos intervalos obrigatórios, atribua Tarefas de indisponibilidade.
• Para tarefas que não são dirigíveis em caixas de depósito ou locais de clientes, atribua Tarefas de parada programada.

Cada tarefa atribuída precisa ter um ID exclusivo, mas as tarefas podem compartilhar o mesmo ID de acompanhamento. Quando o Fleet Engine calcula as janelas de HEC para cada tarefa, ele usa todas as tarefas e a ordem em que estão programadas para fazer estimativas. Para mais informações sobre IDs de tarefas, consulte Diretrizes de IDs de tarefas.

Para criar tarefas no Fleet Engine, use o gerenciador de tarefas do SDK do Driver.

Tarefas de envio

Crie tarefas para retirada e entrega de uma remessa e inclua as seguintes informações:

• O local da retirada ou entrega.
• Um número ou ID de rastreamento.
• Um tempo de permanência para contabilizar o tempo extra para concluir a tarefa, procurar estacionamento ou caminhar até o local de transferência.
• Um ID de tarefa exclusivo. Consulte as diretrizes de IDs de tarefas.

Para encontrar mais informações, consulte os seguintes tópicos:

Android

• Criar uma tarefa de retirada de frete
• Criar uma tarefa de entrega de remessa

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

Tarefas de indisponibilidade

As tarefas de indisponibilidade abrangem períodos em que um veículo não está disponível para retiradas ou entregas, como pausas para reabastecer o veículo ou pausas para descanso do motorista.

Crie uma tarefa de indisponibilidade com as seguintes informações:

• A duração do intervalo.
• Opcionalmente, o local da pausa. Você não precisa informar um local específico, mas isso proporciona janelas de HEC mais precisas ao longo do dia.

Observação: durante uma tarefa de indisponibilidade, nenhuma informação de localização é compartilhada com os usuários finais da biblioteca Shipment Tracking. No entanto, ela está disponível para gerentes de frota que usam a Biblioteca de rastreamento de frota.

Para encontrar mais informações, consulte os seguintes tópicos:

Android

• Indisponibilidade programada

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

Tarefas com paradas programadas

Criar tarefas de paradas programadas para modelar as paradas que um veículo de entrega precisa fazer. Por exemplo, crie uma tarefa de parada programada para uma parada de coleta diária programada em um local específico, independentemente de outras entregas ou embarques no mesmo local. Também é possível criar tarefas de paradas programadas para coletas de caixas de depósito ou para modelar transferências de veículos ou paradas em centros de serviços e pontos de serviço.

Para encontrar mais informações, consulte os seguintes tópicos:

Android

• Paradas programadas

iOS

• GMTD DeliveryTaskManager:
• GMTSTaskType

Diretrizes do ID da tarefa

Ao criar IDs de tarefas, siga estas diretrizes de conteúdo e formato:

• Criar IDs de tarefas exclusivos
• Não exponha informações de identificação pessoal (PII) ou dados de texto claros.
• Use strings Unicode válidas.
• Use até 64 caracteres.
• Não inclua nenhum dos seguintes caracteres ASCII: "/", ":", "\", "?" ou "#".
• Normalize de acordo com o Formulário C de normalização Unicode.

Dica: você pode criar IDs de tarefas usando o mecanismo programático que preferir. O Google recomenda o uso de uma ferramenta UUID versão 4.

Confira abaixo alguns exemplos de IDs de tarefas adequados:

• 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
• e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
• NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

A tabela a seguir mostra exemplos de IDs de tarefas sem suporte:

IDs de tarefas sem suporte	Motivo
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680	Violar as PII e os requisitos de caracteres: vírgulas, pontos, dois-pontos e barras.
JohnDoe-577b484da26f-Cupertino-SantaCruz	Viola os requisitos de PII.
4R0oXLToF"112 Dr. East Hartford, CT06118"577b484da26f8a	Violar os requisitos de PII e caracteres: espaços em branco, vírgulas e aspas. Com mais de 64 caracteres.

Mais recursos

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

Vida útil de um veículo

O objeto DeliveryVehicle representa um veículo de entrega de primeira ou última milha. Crie um objeto DeliveryVehicle usando:

• O ID do projeto do Google Cloud que contém a conta de serviço usada para chamar as APIs do Fleet Engine.
• ID do veículo do cliente

Use documentos de identificação exclusivos para cada veículo. Só reutilize um ID de veículo, a menos que não haja tarefas ativas para o veículo original.

O Fleet Engine exclui automaticamente objetos DeliveryVehicle que não foram atualizados usando UpdateDeliveryVehicle após sete dias. Para verificar se um veículo existe, siga estas etapas:

1. Faça uma chamada para UpdateDeliveryVehicle.
2. Se você receber um erro NOT_FOUND, chame CreateDeliveryVehicle para recriar o veículo. Se a chamada retornar um veículo, ele ainda estará disponível para atualização.

Observação: se você chamar CreateDeliveryVehicle com um par de ID do projeto e do veículo que já existem, vai receber um erro.

Tipos de veículo

A entidade VehicleType contém um campo opcional de VehicleType, que contém um tipo enumerado Category que pode ser especificado como AUTO, TWO_WHEELER, BICYCLE ou PEDESTRIAN. Se você não definir o campo, o padrão será AUTO.

Todos os trajetos para veículos usam o RouteTravelMode correspondente para o tipo de veículo.

Atributos do veículo

A entidade DeliveryVehicle contém um campo repetido de DeliveryVehicleAttribute. A API ListDeliveryVehicles inclui um campo filter que pode limitar as entidades DeliveryVehicle retornadas àquelas com os atributos especificados. DeliveryVehicleAttribute não afeta o comportamento de roteamento do Fleet Engine.

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

A vida de uma tarefa

É possível criar, atualizar e consultar tarefas no Fleet Engine com as interfaces gRPC ou REST da API Deliveries.

Um objeto Task tem um campo de estado para acompanhar a progressão ao longo do ciclo de vida. Os valores se movem de OPEN para CLOSED. Novas tarefas são criadas no estado OPEN, o que indica que:

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

Diretrizes de tarefas

Só é possível atribuir uma tarefa a um veículo quando ele está no estado ABERTO.

Para cancelar uma tarefa, remova-a da lista de paradas de veículos, o que define automaticamente o estado da tarefa como CLOSED.

Quando o veículo da tarefa parar o veículo:

1. Atualize o campo de resultado da tarefa para SUCCEEDED ou FAILED.

   Observação: é possível definir o resultado da tarefa a qualquer momento antes ou depois da conclusão da tarefa, mas só é possível defini-lo uma vez.

2. Especifique o carimbo de data/hora do evento.

   A biblioteca JavaScript Shipment Tracking indica o resultado da tarefa, e o status dela é definido automaticamente como CLOSED. Para saber mais, consulte Rastrear seu envio com a biblioteca JavaScript Shipment Tracking.

Assim como nos veículos, o Fleet Engine exclui tarefas que não foram atualizadas após sete dias e, se você tentar criar uma tarefa com um ID que já existe, ela retornará um erro.

Observação:o Fleet Engine não dá suporte à exclusão explícita de uma tarefa. O serviço exclui tarefas automaticamente após sete dias sem atualizações. Se quiser reter dados de tarefas por mais de sete dias, implemente esse recurso por conta própria.

Atributos da tarefa

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

Não inclua informações de identificação pessoal (PII) ou outras informações sensíveis nos atributos, porque eles podem ser visíveis aos usuários.

Gerencie o ciclo de vida do veículo e da tarefa

Lembrete: seu sistema interno atua como a fonte confiável dos dados que a API Fleet Engine Deliveries aumenta em seu nome.

Para gerenciar os ciclos de vida do veículo e das tarefas no sistema, use a API Fleet Engine Deliveries para criar, atualizar e rastrear seus veículos e as tarefas associadas a eles.

Ao mesmo tempo, o aplicativo do motorista se comunica diretamente com o Fleet Engine para atualizar as informações de localização e trajeto do dispositivo. Com esse modelo, o Fleet Engine gerencia a localização em tempo real com eficiência. Ele envia o local diretamente para a biblioteca de rastreamento, que pode ser usada para atualizar os consumidores sobre o status do pedido.

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

• Um motorista se aproximando de uma parada de entrega. O aplicativo do motorista envia a localização ao Fleet Engine.
• O Fleet Engine envia a localização do dispositivo para a biblioteca de rastreamento, que o aplicativo do 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.
• A ação "Envio entregue" envia as informações para seu sistema de back-end, que executa as etapas necessárias de validação e verificação de negócios.
• O sistema confirma a tarefa como CONCLUÍDA e atualiza o Fleet Engine usando a API Deliveries.

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

Gerenciar tokens do cliente

As atualizações de localização originadas do aplicativo do driver e enviadas diretamente ao Fleet Engine exigem tokens de autorização. Esta é a abordagem recomendada para lidar com atualizações do cliente para o Fleet Engine:

1. Gere o token usando o papel da conta de serviço Usuário de driver não confiável da entrega do Fleet Engine.

2. Fornecer um token de escopo limitado ao aplicativo do driver. Esse escopo só permite atualizar o local do dispositivo no Fleet Engine.

Essa abordagem garante que as chamadas originadas de dispositivos móveis (considerados ambientes de baixa confiança) sigam o princípio de privilégio mínimo.

Outros papéis da conta de serviço

Se, em vez disso, você quiser autorizar os aplicativos de driver a fazer atualizações diretas do Fleet Engine além das restritas ao papel de driver não confiável, por exemplo, para determinadas atualizações de tarefas, use o papel de driver confiável. Para informações sobre um modelo que usa o papel de Motorista Confiável, consulte Modelo de Motorista Confiável.

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

Planeje um dia de trabalho

A tabela a seguir descreve como pode ser um dia de trabalho para motoristas de primeira ou última milha para uma empresa de entrega e logística. Os detalhes da sua empresa podem diferir, mas você pode ver como modelar um dia de trabalho.

Tempo	Atividade	Modelagem
Dentro de 24 horas a partir do início do dia	O agente atribui remessas a veículos ou rotas de entrega.	É possível criar tarefas para entregas de remessa, retiradas, intervalos e outras com antecedência no Fleet Engine. Por exemplo, é possível criar uma tarefa de retirada do envio, tarefa de entrega de envio, indisponibilidade programada ou parada programada. Atribua tarefas a um veículo quando o conjunto de pacotes de entrega e a ordem em que eles precisam ser entregues forem finalizados.
Início do dia	O motorista começa o dia no depósito fazendo login no app.	Inicialize a API Delivery Driver. Crie o veículo de entrega no Fleet Engine, conforme necessário.
	O motorista carrega as remessas no veículo de entrega, digitalizando as remessas.	Se as tarefas de entrega da remessa não foram criadas antecipadamente, crie tarefas de entrega de remessa no momento da leitura.
	O motorista confirma a ordem das tarefas a serem realizadas.	Caso não tenham sido criados com antecedência, crie tarefas de retirada de envio, indisponibilidade programada e paradas programadas.
	O driver sai do depósito e confirma para o próximo número de tarefas a serem concluídas.	Atribua todas as tarefas ou um subconjunto de tarefas ao veículo confirmando a ordem de conclusão.
	O motorista entrega uma remessa.	Depois de chegar à parada de entrega, realize ações relacionadas a um veículo chegando a uma parada. Depois de entregar a remessa, feche a tarefa de entrega e, se quiser, status do envio da loja e outras informações meta. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo a caminho da próxima parada.
	O motorista encontra um veículo alimentador para transferir remessas adicionais para o veículo de entrega.	O ponto de encontro de uma baldeação entre o alimentador e os veículos de entrega precisa ser modelado como uma parada programada. Depois de transferir e digitalizar as remessas, crie tarefas de entrega se elas ainda não tiverem sido criadas. Em seguida, atualize a ordem de conclusão da tarefa atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
	O motorista recebe uma notificação de 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 das tarefas atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
Meio-dia	Motorista faz uma pausa para o almoço.	Se um local estiver associado à tarefa de indisponibilidade, trate-o como qualquer outra tarefa. Realize ações relacionadas a um veículo chegando em uma parada, veículo conclui uma parada e veículo a caminho da próxima parada. Caso contrário, nenhuma outra ação é necessária até o fim do intervalo. Remova a tarefa confirmando as tarefas seguintes e restantes e atualizando a ordem das tarefas.
	O motorista pega uma remessa.	Isso é modelado como uma parada de entrega. Realize ações relacionadas a um veículo que chega a uma parada, fecha uma tarefa e, opcionalmente, armazenar o status da remessa e outras informações meta. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo a caminho da próxima parada. Observação: para garantir o faturamento correto, todas as retiradas precisam ter uma tarefa de entrega correspondente. Se a retirada for entregue em outro local no mesmo trajeto do motorista no dia, recomendamos modelar essa tarefa de entrega como qualquer outra tarefa de entrega no trajeto. Se o motorista estiver trazendo a retirada de volta ao depósito, recomendamos criar uma tarefa de entrega no destino.
	O motorista faz uma parada programada para retirar as remessas em uma caixa de depósito.	Ela é modelada da mesma forma que qualquer outra parada de embarque. Realize ações relacionadas a um veículo chegando em uma parada e fechando uma tarefa. Depois de concluir todas as tarefas na parada e começar a dirigir até a próxima parada, execute ações relacionadas a veículo conclui uma parada e veículo a caminho da próxima parada.
	O motorista recebe uma notificação de que uma remessa foi desviada para um local alternativo.	Defina o status 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 interrupção de entrega bem-sucedida, marcando a tarefa de entrega como concluída. Realize ações relacionadas a um veículo chegando em uma parada. Depois de não entregar a remessa, feche a tarefa e, se quiser, o status da remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo a caminho da próxima parada.
	O motorista foi notificado para reter (não entregar) uma remessa.	Depois que a notificação for recebida e confirmada, defina o status da tarefa como CONCLUÍDA.
	O motorista foi notificado para entregar determinada remessa em seguida, alterando o pedido de entrega confirmado.	Atualizar a ordem das tarefas.
	O motorista decide entregar uma remessa fora de ordem.	Atualize a ordem das tarefas e continue normalmente.
	O motorista entrega várias encomendas para um único local.	Isso é modelado de maneira semelhante a uma única parada de entrega de remessa. Depois de chegar à parada, realize ações relacionadas a um veículo chegando a uma parada. Depois de entregar cada remessa, feche cada tarefa e, opcionalmente, o status da remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo a caminho da próxima parada.
Fim do dia	O motorista retorna ao depósito.	Se o motorista retornar ao depósito com remessas retiradas durante o trajeto, você também precisará criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. É possível fazer isso modelando o depósito como qualquer outra parada de entrega. Se o depósito não estiver sendo usado como uma parada de entrega, ainda será possível modelar o depósito como uma parada programada. Isso permite que os motoristas vejam o trajeto de volta até o depósito e saibam o horário estimado de chegada.

Como funcionam as atualizações de localização

Para ter o melhor desempenho com o Fleet Engine, forneça um fluxo de atualizações de localização do veículo. Use uma das seguintes maneiras para fornecer essas atualizações:

1. Use o SDK do Driver: Android e iOS, que é a opção mais simples.
2. Use o código personalizado: útil se os locais forem transmitidos pelo seu back-end ou se você usar dispositivos que não sejam Android ou iOS.

Independentemente de como você fornece atualizações de localização do veículo, o back-end é responsável por atualizar o Fleet Engine quando um veículo de entrega está a caminho de uma parada (incluindo a estação) e quando ele chega a uma parada. O Fleet Engine não detecta esses eventos automaticamente.

Paradas e locais de entrega de veículos

Uma parada de veículo é onde um veículo de entrega conclui uma tarefa de envio ou alguma outra tarefa. Ele é um ponto de acesso, como uma doca de carregamento, ou um local posicionado na estrada.

O local de entrega é o local em que 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 de uma loja em um shopping, o veículo de entrega para no estacionamento do shopping, perto da 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 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 do veículo e lembre-se de que o número de paradas restantes do veículo para as tarefas de frete é informado ao usuário para ajudá-lo a visualizar o andamento da remessa.

Por exemplo, se um motorista estiver fazendo muitas entregas em um único prédio comercial, considere atribuir todas as tarefas de entrega a uma única parada de veículo. Se cada tarefa de entrega for atribuída a uma parada de veículo, sua experiência de rastreamento de remessas será menos útil para os usuários, já que esse recurso só estará disponível quando o veículo estiver dentro de um número limitado de paradas antes do destino. Fazer muitas paradas de veículos em um curto período não dá ao usuário muito tempo para acompanhar o andamento da entrega.

Usar os SDKs para dispositivos móveis

Antes de fazer chamadas para o SDK do Driver, inicialize-o.

Inicializar a API Delivery Driver

Antes de inicializar a API Delivery Driver no SDK do Driver, inicialize o SDK do Navigation. Em seguida, inicialize a API Delivery Driver, conforme mostrado no exemplo a seguir:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }
     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

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 exclusivos de entidade

O formato e o valor dos identificadores exclusivos de entidade usados em chamadas REST são opacos para o Fleet Engine. Evite usar IDs com incremento automático e verifique se o identificador não contém informações de identificação pessoal (PII), como o número de telefone do motorista.

Criar um veículo

Você pode criar um veículo a partir do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST.

gRPC

Para criar um veículo novo, faça uma chamada CreateDeliveryVehicle para o Fleet Engine. Use o objeto CreateDeliveryVehicleRequest para definir os atributos do 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, também é possível especificar estes campos:

• Atributos
• LastLocation
• Tipo

Não defina outros campos. Se você fizer isso, o Fleet Engine retornará um erro porque esses campos são somente leitura ou só podem ser atualizados com uma chamada para UpdateDeliveryVehicle.

Para criar um veículo sem definir campos opcionais, deixe o campo DeliveryVehicle sem definição 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 a partir de um ambiente de servidor, faça uma chamada HTTP REST para CreateDeliveryVehicle:

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

<id> é um identificador exclusivo de um veículo de entrega na sua frota.

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

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

• atributos
• lastLocation
• Tipo

Comando curl de exemplo:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

O Fleet Engine ignora o campo name da entidade DeliveryVehicle de acordo com a orientação da API para IDs especificados pelo usuário. Não defina outros campos. Se você fizer isso, o Fleet Engine retornará um erro porque esses campos são somente leitura ou só podem ser atualizados usando uma chamada para UpdateDeliveryVehicle.

Para criar um veículo sem definir nenhum campo, deixe o corpo da solicitação POST em branco. O veículo recém-criado extrai um ID de veículo do parâmetro deliveryVehicleId no URL POST.

Comando curl de exemplo:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Criar uma tarefa de retirada de frete

É possível criar uma tarefa de retirada de frete no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tem IDs de tarefas no seu sistema, pode gerar um identificador universalmente exclusivo (UUID).

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

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

• Campos obrigatórios:

  Field	Valor
  Tipo	Type.PICKUP
  state	State.OPEN
  trackingId	O número ou identificador que você está usando para rastrear um envio.
  plannedLocation	O local em que a tarefa será concluída. Neste caso, o local de retirada da remessa.
  taskDuration	O tempo esperado, em segundos, que leva para retirar a remessa no local de retirada.

• Campos opcionais:

  Field	Valor
  targetTimeWindow	A janela de tempo em que a tarefa deve ser concluída. Isso não afeta o comportamento de roteamento.
  atributos	Uma lista de atributos de tarefas personalizados. Cada atributo precisa ter uma chave exclusiva.

Todos os outros campos da entidade são ignorados para criação. O Fleet Engine gera uma exceção se a solicitação inclui um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequest. Para mais informações, consulte Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.

Comando curl de exemplo:

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

Criar uma tarefa de entrega de remessa

Crie uma tarefa de entrega de remessa com o SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

Para criar uma tarefa de entrega de remessa de um ambiente de servidor usando gRPC ou REST, faça uma chamada HTTP REST para CreateTask:

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

<id> é um identificador exclusivo da tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tem IDs de tarefas no seu sistema, pode gerar um identificador universalmente exclusivo (UUID).

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

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

• Campos obrigatórios:

  Field	Valor
  Tipo	Type.DELIVERY
  state	State.OPEN
  trackingId	O número ou identificador que você está usando para rastrear um envio.
  plannedLocation	O local em que a tarefa será concluída. Neste caso, o local de entrega da remessa.
  taskDuration	O tempo esperado, em segundos, que leva para entregar o pacote no local de entrega.

• Campos opcionais:

  Field	Valor
  targetTimeWindow	A janela de tempo em que a tarefa deve ser concluída. Isso não afeta o comportamento de roteamento.
  atributos	Uma lista de atributos de tarefas personalizados. Cada atributo precisa ter uma chave exclusiva.

Todos os outros campos da entidade são ignorados para criação. O Fleet Engine gera uma exceção quando a solicitação inclui um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequest. Para mais informações, consulte Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.

Comando curl de exemplo:

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

Tarefas de criação em lote

É possível criar um lote de tarefas em um ambiente de servidor usando gRPC ou REST.

gRPC

O exemplo a seguir mostra como usar 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 entrega e uma tarefa de retirada em um ambiente de servidor, faça uma chamada HTTP REST para BatchCreateTasks:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

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

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

• Campos obrigatórios:

  Field	Valor
  solicita	Matriz<CreateTasksRequest>

• Campos opcionais:

  Field	Valor
  cabeçalho	"DeliveryRequestHeader"

Cada elemento CreateTasksRequest em requests precisa transmitir as mesmas regras de validação que uma solicitação CreateTask, com exceção dos campos parent e header. Se definidos, eles precisarão ser idênticos aos respectivos campos no nível superior BatchCreateTasksRequest. Consulte Criar uma tarefa de retirada 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 indique indisponibilidade (por exemplo, para quebras do motorista ou reabastecimento de veículos) no SDK do motorista ou em um ambiente de servidor usando gRPC ou REST. Uma tarefa de indisponibilidade programada não pode incluir um ID de rastreamento. 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 em um ambiente de servidor, faça uma chamada HTTP REST para CreateTask:

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

<id> é um identificador exclusivo da tarefa. Se você não tem IDs de tarefas no seu sistema, pode gerar um identificador universal exclusivo (UUID).

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

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

• Campos obrigatórios:

  Field	Valor
  Tipo	Type.UNAVAILABLE
  state	State.OPEN
  taskDuration	A duração do intervalo em segundos.

• Campos opcionais:

  Field	Valor
  plannedLocation	Local da pausa, se ela precisar ser realizada em um local específico.

Todos os outros campos da entidade são ignorados para criação. O Fleet Engine gera uma exceção quando a solicitação inclui um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequest. Para mais informações, consulte Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.

Comando curl de exemplo:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

Paradas programadas

É possível criar uma tarefa de parada programada usando o SDK do driver ou em um ambiente de servidor usando gRPC ou REST. Uma tarefa de parada programada pode não incluir um ID de rastreamento.

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 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 da tarefa. Se você não tem IDs de tarefas no sistema, é possível gerar um identificador universalmente exclusivo (UUID).

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

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

• Campos obrigatórios:

  Field	Valor
  Tipo	Type.SCHEDULED_STOP
  state	State.OPEN
  plannedLocation	O local da parada.
  taskDuration	A duração prevista da parada em segundos.

• Campos opcionais:

  • Nenhum

Todos os outros campos da entidade são ignorados para criação. O Fleet Engine gera uma exceção quando a solicitação inclui um deliveryVehicleId atribuído. Você atribui tarefas usando UpdateDeliveryVehicleRequest. Para mais informações, consulte Atribuir tarefas a um veículo e UpdateDeliveryVehicleRequest.

Comando curl de exemplo:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

Definir janela de tempo desejada

A janela de tempo desejada é a TimeWindow em que a tarefa será concluída. Por exemplo, se você comunicar uma janela de tempo de entrega aos destinatários da entrega, poderá usar a janela de tempo desejada da tarefa para capturar essa janela de tempo e gerar alertas ou analisar o desempenho pós-viagem usando o campo.

A janela de horário desejado consiste em um horário de início e um de término e pode ser definida em qualquer tipo de tarefa. A janela de tempo de destino não afeta o comportamento do roteamento.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir uma janela de tempo de tarefa:

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa.

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

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

• Campos obrigatórios:

  Field	Valor
  targetTimeWindow	A janela de tempo em que a tarefa deve ser concluída. Essa configuração não afeta o comportamento de roteamento

• Campos opcionais:

  • Nenhum

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

Comando curl de exemplo:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Definir a configuração de visibilidade do rastreamento de tarefas

A visibilidade dos dados na biblioteca Shipment Tracking e dos dados retornados de uma chamada para GetTaskTrackingInfo pode ser controlada por tarefa definindo um TaskTrackingViewConfig na tarefa. Consulte Tarefas com veículos ativos para mais informações. Isso pode ser feito ao criar ou atualizar a tarefa. Veja a seguir um exemplo de como atualizar a tarefa com essa configuração:

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir a configuração de visualização do rastreamento de tarefas:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

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

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

REST

Para definir a janela de configuração da visualização do rastreamento de tarefas usando HTTP, chame UpdateTask:

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

<id> é um identificador exclusivo da tarefa.

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

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

• Campos obrigatórios:

  Field	Valor
  taskTrackingViewConfig	A configuração do rastreamento de tarefas que especifica quais elementos de dados ficam visíveis para os usuários finais em quais circunstâncias.

• Campos opcionais:

  • Nenhum

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

Comando curl de exemplo:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

Atribuir tarefas a um veículo

Você atribui tarefas a um veículo de entrega atualizando a ordem das tarefas dele. A ordem das tarefas de um veículo é determinada pela lista de paradas do veículo de entrega, e você pode atribuir uma ou mais tarefas a cada parada do veículo. Para mais detalhes, consulte Atualizar a ordem das tarefas.

Para mudar uma remessa de um veículo para outro, feche a tarefa original e recrie-a antes de atribuir o novo veículo. Se você atualizar a ordem de uma tarefa que já está atribuída a um veículo diferente, receberá um erro.

Atualizar a ordem das tarefas

É possível atualizar as tarefas do pedido atribuídas a um veículo que são realizadas no SDK do motorista ou no ambiente do servidor. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

Quando você atualiza a ordem de tarefas para um veículo, ele também faz o seguinte:

• Atribui tarefas novas ao veículo.
• Fecha todas as tarefas que foram atribuídas anteriormente ao veículo, mas que não estão na ordem atualizada.

Para mudar uma remessa de um veículo para outro, feche a tarefa original e recrie-a antes de atribuir o novo veículo a ela. Se você atualizar a ordem de uma tarefa que já está atribuída a um veículo diferente, receberá um erro.

Você pode atualizar a ordem das tarefas a qualquer momento.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para atualizar a ordem 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 de tarefas de um veículo em um ambiente de servidor, faça uma chamada HTTP REST para UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> é um identificador exclusivo de um veículo de entrega na sua frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou ao criar o veículo.

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

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

• Campos obrigatórios:

  Field	Valor
  remainingVehicleJourneySegments	Uma lista de segmentos da jornada para tarefas na ordem em que devem ser executadas. A primeira tarefa da lista é executada primeiro.
  VehicleJourneySegments[i].stop	A parada da tarefa i na lista.
  VehicleJourneySegments[i].stop.plannedLocation	O local planejado para a parada.
  VehicleJourneySegments[i].stop.tasks restantes	Uma lista de tarefas a serem realizadas nesta parada de veículo.
  remainingVehicleJourneySegments[i].stop.state	State.NEW

• Campos opcionais:

  • Nenhum

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

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido 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 Fleet Engine precisa ser notificado quando um veículo sai de uma parada ou inicia a navegação. É possível notificar o Fleet Engine no SDK do driver ou em um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para notificar o Fleet Engine de que um veículo está a caminho da próxima parada.

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
        // Next stop marked as ENROUTE
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.7749)
                       .setLongitude(122.4194)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
               .setState(VehicleStop.State.ENROUTE)))
        // All other stops marked as NEW
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.3382)
                       .setLongitude(121.8863)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
               .setState(VehicleStop.State.NEW)))
        .build();

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

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

REST

Para notificar o Fleet Engine de que um veículo está a caminho da próxima parada em um ambiente de servidor, faça uma chamada REST HTTP para UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> é um identificador exclusivo do veículo de entrega na sua frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou ao criar o veículo.

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

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

• Campo obrigatório:

  Field	Valor
  remainingVehicleJourneySegments	Lista de paradas de veículos restantes com os estados marcados como State.NEW. A primeira parada da lista precisa ter o estado marcado como State.ENROUTE.

• Campos opcionais:

  • Nenhum

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

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido 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

Atualizar localização do veículo

Se você não estiver usando o SDK do Driver para atualizar a localização do veículo, poderá fazer uma chamada direta para o Fleet Engine com a localização do veículo. Para qualquer veículo ativo, o Fleet Engine espera uma atualização de local pelo menos uma vez por minuto e no máximo uma vez a cada cinco segundos.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para atualizar a localização de um veículo no Fleet Engine:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .build();

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

REST

Para atualizar a localização de um veículo no Fleet Engine usando HTTP REST, faça uma chamada para UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`

<id> é um identificador exclusivo do veículo de entrega da sua frota ou que você pretende atualizar o local. É o identificador que você especificou ao criar o veículo.

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

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

• Campo obrigatório:

  Field	Valor
  lastLocation.supplementalLocation	A localização do veículo.
  lastLocation.supplementalLocationTime	O último carimbo de data/hora conhecido em que o veículo esteve nesse local.
  lastLocation.supplementalLocationSensor	Deve ser preenchido com CUSTOMER_SuppPLIED_LOCATION.

• Campos opcionais:

  Field	Valor
  lastLocation.supplementalLocationAccuracy	Precisão da localização fornecida, em metros.

Comando curl de exemplo:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

O veículo chega a uma parada

O Fleet Engine precisa ser notificado quando um veículo chega a uma parada. Você pode notificar o Fleet Engine do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte 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 em uma parada em um ambiente de servidor, faça uma chamada REST HTTP para UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> é um identificador exclusivo do veículo de entrega na sua frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou ao criar o veículo.

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

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

• Campos obrigatórios:

  Field	Valor
  remainingVehicleJourneySegments	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 da entidade são ignorados na atualização.

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido 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 Fleet Engine precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada sejam definidas com o estado CLOSED. É possível notificar o Fleet Engine no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para notificar o Fleet Engine de que um veículo concluiu uma parada.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

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

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

REST

Para notificar o Fleet Engine sobre a conclusão de uma parada em um ambiente de servidor, faça uma chamada HTTP REST para UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id> é um identificador exclusivo do veículo de entrega na sua frota em que você pretende atualizar a ordem das tarefas. É o identificador que você especificou ao criar o veículo.

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

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

• Campos obrigatórios:

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

• Campos opcionais:

  • Nenhum

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

Comando curl de exemplo:

Observação: esse comando substitui qualquer remainingVehicleJourneySegments já definido 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}"
              }
            ]
          }
        }
      ]
    }
    EOM

Atualizar uma tarefa

A maioria dos campos de tarefa é imutável. No entanto, é possível modificar o estado, o resultado, o horário e o local do resultado da tarefa, bem como 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 fechá-la atualizando o estado diretamente.

gRPC

Este é um exemplo de atualização de uma tarefa por meio do gRPC.

REST

Este é um exemplo de atualização de uma tarefa pelo REST.

Fechar uma tarefa

Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada em que a tarefa ocorre ou remova-a da lista de paradas do veículo. Para isso, você pode definir a lista de paradas restantes do veículo assim como 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 CLOSED. No entanto, não é possível reabrir uma tarefa CLOSED.

O fechamento de uma tarefa não indica sucesso ou falha. Ele indica que a tarefa não é mais considerada em andamento. No rastreamento de remessas, é 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) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

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

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

REST

Para marcar uma tarefa como fechada em um ambiente de servidor, faça uma chamada HTTP REST para UpdateTask:

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

<id> é um identificador exclusivo da tarefa.

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

Você precisa incluir uma entidade Task no corpo da solicitação:

• Campos obrigatórios:

  Field	Valor
  state	State.CLOSED

• Campos opcionais:

  Field	Valor
  taskOutcome	Outcome.SUCCEEDED ou Outcome.FAILED
  taskOutcomeTime	A hora em que a tarefa foi concluída.
  taskOutcomeLocation	O local em que a tarefa foi concluída. O padrão do Fleet Engine é a última localização do veículo, a menos que seja substituído manualmente pelo provedor.

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

Comando curl de exemplo:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "state": "CLOSED",
      "taskOutcome": "SUCCEEDED",
      "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
    }
    EOM

Definir o resultado da tarefa e o local dos resultados

O encerramento de uma tarefa não indica sucesso ou falha, mas indica que a tarefa não é mais considerada em andamento. No rastreamento de remessas, é importante indicar o resultado real de uma tarefa para que ele possa ser mostrado e haja faturamento adequado pelos serviços. Depois de definido, não é possível mudar o resultado da tarefa. No entanto, é possível modificar o tempo e o local do resultado da tarefa depois de definidos.

As tarefas no estado CLOSED podem ter os resultados definidos como SUCCEEDED ou FAILED. O Fleet Engine cobra apenas as tarefas de entrega com estado SUCCEEDED.

Ao marcar o resultado de uma tarefa, o Fleet Engine preenche automaticamente o local dele com a última localização conhecida do veículo. É possível substituir esse comportamento.

gRPC

Você tem a opção de definir o local do resultado da tarefa ao definir o resultado. Definir o local impede que o Fleet Engine o defina como padrão do último local do veículo. Também é possível substituir o local do resultado da tarefa definido pelo Fleet Engine mais tarde. O Fleet Engine nunca substitui um local de resultado de tarefa fornecido por você. Não é possível definir um local de resultados para uma tarefa que não tenha um conjunto desse tipo. É possível definir o resultado e o local 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 da tarefa.

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

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

• Campos obrigatórios:

  Field	Valor
  taskOutcome	Outcome.SUCCEEDED ou Outcome.FAILED

• Campos opcionais:

  Field	Valor
  taskOutcomeLocation	O local em que a tarefa foi concluída. Se ela não for definida, o Fleet Engine usará como padrão a última localização do veículo.
  taskOutcomeTime	O carimbo de data/hora em que a tarefa foi concluída.

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

Comando curl de exemplo:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Redirecionar uma remessa

Depois que uma tarefa de remessa é criada, o local planejado não pode ser alterado. Para redirecionar uma remessa, feche a tarefa de envio sem 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 envio e atribuir a tarefa.

Usar alimentador e veículos de entrega

Se você usa veículos alimentadores para transportar remessas para veículos de entrega ao longo do dia, 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, 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 metainformações

Quando uma tarefa de frete é concluída, o estado e o resultado dela são registrados na tarefa. No entanto, convém atualizar outras metainformações específicas do envio. Para armazenar outras informações meta que possam ser referenciadas fora do serviço do Fleet Engine, use o "tracking_id" associado à tarefa como uma chave em uma tabela externa.

Para mais informações, consulte O ciclo de uma tarefa.

Procurar um veículo

É possível procurar um veículo no SDK do Driver ou em um ambiente de servidor usando gRPC ou REST.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para procurar um veículo:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

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

REST

Para procurar um veículo em um ambiente de servidor, faça uma chamada HTTP REST para GetVehicle:

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

<id> é um identificador exclusivo da tarefa.

<vehicleId> é o ID do veículo a ser pesquisado.

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

O corpo da solicitação precisa estar vazio.

Se a pesquisa for bem-sucedida, o corpo da resposta vai incluir uma entidade de veículo.

Comando curl de exemplo:

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

Procurar uma tarefa

É possível pesquisar uma tarefa em um ambiente de servidor usando gRPC ou REST. O SDK do Driver não 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 da tarefa.

<taskId> é o código da tarefa a ser pesquisada.

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

O corpo da solicitação precisa estar vazio.

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

Comando curl de exemplo:

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

Procurar as informações da tarefa de envio pelo ID de rastreamento

É possível procurar informações sobre as tarefas de remessa das seguintes maneiras, cada uma com uma finalidade separada:

• por um ID de tarefa: usado por usuários, como operadores de frota que têm acesso à visualização completa dos dados da tarefa.
• por um ID de acompanhamento: usado pelo seu software cliente para fornecer informações limitadas a um usuário final, como quando um pacote é entregue na casa dele.

Esta seção discute a busca de informações de tarefas por um ID de acompanhamento. Se você quiser pesquisar uma tarefa pelo ID, acesse Procurar uma tarefa.

Para procurar informações por um ID de acompanhamento, você pode usar uma das opções a seguir:

• Pesquisas com Java usando gRPC
• Pesquisas usando HTTP

Requisitos de pesquisa

• As informações de envio fornecidas por um ID de rastreamento obedecem às regras de visibilidade estabelecidas em Controlar a visibilidade dos locais rastreados.

• Use o Fleet Engine para procurar informações de envio pelo ID de rastreamento. O SDK do driver não oferece suporte a pesquisas de informações por ID de acompanhamento. Para fazer isso com o Fleet Engine, use um ambiente de servidor ou navegador.

• Use o token mais estreito possível para limitar os riscos de segurança. Por exemplo, se você usar um token de consumidor de entrega, todas as chamadas da API Fleet Engine Deliveries retornarão apenas informações relevantes para esse usuário final, como o remetente ou o destinatário de uma remessa. Todas as outras informações nas respostas são encobertas. Para saber mais sobre tokens, consulte Como criar um JSON Web Token (JWT) para autorização.

Pesquisas com Java usando gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para procurar informações sobre uma tarefa de envio pelo ID de rastreamento.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Pesquisas usando HTTP

Para procurar uma tarefa de remessa 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 de navegador. O SDK do Driver não oferece suporte à listagem de tarefas.

A listagem de tarefas solicita amplo acesso às tarefas. As tarefas de listagem são destinadas apenas a usuários confiáveis. Use os tokens de autenticação de superusuário de entrega ou de leitor de frota de entrega ao fazer solicitações de tarefas de lista.

As tarefas listadas têm os seguintes campos encobertos:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

As tarefas listadas podem ser filtradas pela maioria das propriedades de tarefa. Para conferir a sintaxe da consulta de filtro, consulte AIP-160. A lista a seguir mostra propriedades de tarefa válidas que podem ser usadas para filtragem:

• atributos
• delivery_vehicle_id
• state
• planned_location
• task_duration
• task_outcome
• task_outcome_location
• task_outcome_location_source
• task_outcome_time
• tracking_id
• Tipo

Use os seguintes formatos de campo com base nas propostas de melhoria da API do Google:

Tipo de campo	Formato	Exemplo
Carimbo de data/hora	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Duração	Número de segundos seguidos por um s	task_duration = 120s
Tipo enumerado	String	state = CLOSED AND type = PICKUP
Local	point.latitude e point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Consulte AIP-160 para ver uma lista completa de operadores de consulta de filtro.

Se nenhuma consulta de filtro for especificada, todas as tarefas serão listadas.

As listas de tarefas são paginadas. Um tamanho de página pode ser especificado em solicitações de lista de tarefas. Se um tamanho de página for especificado, o número de tarefas retornadas não será maior que o tamanho da página 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 leitura da próxima página de resultados. Use o token de página com uma solicitação que seja idêntica à solicitação 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 em atributos de tarefa pode fazer com que a latência de recuperação aumente significativamente e precisa ser usada 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 REST HTTP 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 "filter" com uma consulta de filtro com escape de URL como valor.

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

Se a pesquisa for bem-sucedida, o corpo da resposta 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 foi encontrada nenhuma tarefa que atendesse aos critérios de filtro especificados.

Comando curl de exemplo:

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Listar veículos de entrega

É possível listar veículos de entrega de um ambiente de servidor ou navegador. O SDK do motorista não oferece suporte à listagem de veículos de entrega.

A listagem de veículos de entrega solicita amplo acesso a veículos de entrega e é destinada apenas a usuários confiáveis. Use o leitor de frota de entrega ou os tokens de autenticação de superusuário de entrega ao fazer solicitações de lista de veículos de entrega.

Os veículos de entrega listados têm os seguintes campos encobertos devido ao impacto no tamanho da resposta:

• CurrentRouteSegment
• RemainingVehicleJourneySegments

É possível filtrar os veículos de entrega da lista pela propriedade attributes. Por exemplo, para consultar um atributo com a chave my_key e o valor my_value, use attributes.my_key = my_value. Para consultar vários atributos, mescle as consultas usando os operadores lógicos AND e OR, como em attributes.key1 = value1 AND attributes.key2 = value2. Consulte AIP-160 para ver uma descrição completa da sintaxe da consulta de filtro.

É possível filtrar os veículos de entrega listados por local usando o parâmetro de solicitação viewport. O parâmetro de solicitação viewport define janelas de visualização usando duas coordenadas delimitadoras: um par de coordenadas de latitude e longitude high (nordeste) e low (sudoeste). As solicitações serão rejeitadas se contiverem uma latitude alta geograficamente menor do que uma latitude baixa.

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

Por padrão, as listas de veículos de entrega são paginadas com um tamanho de página razoável. Se você especificar um tamanho de página, a solicitação retornará apenas o número de veículos especificados 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ó estará presente em uma resposta quando mais páginas de veículos de entrega estiverem disponíveis para recuperação. Para acessar a próxima página de tarefas, use o token da página com uma solicitação que seja idêntica à solicitação anterior.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para listar veículos de entrega em uma região específica com um determinado atributo. Uma resposta bem-sucedida ainda pode estar vazia. Quando isso acontece, nenhum veículo com o atributo especificado já está na janela de visualização especificada.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

Para listar tarefas em um navegador, faça uma chamada REST HTTP para ListDeliveryVehicles:

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

Para aplicar um filtro às tarefas listadas, inclua um parâmetro de URL "filter" com uma consulta de filtro com escape de URL como valor.

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

Se a pesquisa for bem-sucedida, o corpo da resposta 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, nenhum veículo de entrega foi encontrado atendendo à consulta de filtro e à janela de visualização especificadas.

Comando curl de exemplo:

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

Rastreamento de envio

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

• Preferencial:use a biblioteca JavaScript Shipment Tracking. A biblioteca permite visualizar a localização de veículos e locais de interesse rastreados no Fleet Engine. Ele contém um componente de mapa JavaScript que é uma substituição simples para um objeto google.maps.Map padrão e componentes de dados para se conectar ao Fleet Engine. Esse componente permite fornecer uma experiência personalizável e animada de rastreamento de frete pelo seu aplicativo da Web ou para dispositivos móveis.

• Implemente seu próprio rastreamento de remessas com base na API Fleet Engine Deliveries.

O segredo é procurar tarefas de frete pelo ID de rastreamento.

Se você usar um papel de consumidor de entrega, todas as chamadas da API Fleet Engine Deliveries retornarão apenas informações relevantes para um remetente ou um destinatário. Todas as outras informações nas respostas são encobertas. Você é responsável por autenticar os usuários finais. Além disso, as informações de localização são filtradas com base na tarefa já realizada. Durante uma tarefa de indisponibilidade, nenhuma informação de localização é compartilhada com o usuário final.

Geração de registros

É possível configurar o Fleet Engine para enviar registros de RPC ao Cloud Logging. Para saber mais, consulte Logging.

Papéis e tokens de autorização

Conforme descrito em Gerenciar o ciclo de vida do veículo e da tarefa e nas notas de autorização para casos de uso individuais, fazer chamadas para o Fleet Engine requer autenticação com JSON Web Tokens que foram assinados usando credenciais de conta de serviço. As contas de serviço usadas para emitir esses tokens podem ter um ou mais papéis, em que cada papel concede um conjunto diferente de permissões.

Para mais informações, consulte Autenticação e autorização.

Solução de problemas comuns

Consulte as seções a seguir para receber ajuda se você tiver algum problema.

Resiliência

A Fleet Engine não é considerada uma fonte de verdade. Você é responsável por restaurar o estado do sistema, se necessário, sem depender do mecanismo de frota.

Estado perdido no Fleet Engine

Ao trabalhar com o Fleet Engine, implemente clientes para que o sistema se recupere em caso de falha. Por exemplo, quando o Fleet Engine tenta atualizar um veículo, ele pode responder com um erro indicando que o veículo não existe. O cliente precisa recriar o veículo no novo estado. Embora esse problema raramente ocorra, verifique se o sistema é resiliente o suficiente para lidar com ele.

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 há verificações de cota 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.

Perda de estado no app do motorista

Se o app do driver falhar, o app precisará recriar o estado atual no SDK do driver. O app precisa tentar recriar tarefas para garantir que elas existam e restaurar os estados atuais. O app também precisa recriar e definir explicitamente a lista de paradas para o SDK do motorista.

Observação: essas restaurações precisam ser feitas de forma autônoma, sem depender de informações do Fleet Engine, além de 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 dela.

Perguntas frequentes

E se um motorista parar devido a uma tarefa fora de ordem?

Nesse caso, primeiro atualize a ordem das tarefas e continue normalmente, marcando a chegada na parada, a conclusão da tarefa e outros detalhes. Caso contrário, o sistema pode ficar inconsistente, os ETAs podem ficar incorretos e erros inesperados podem ser relatados.