Comece a usar o Fleet Engine para rastreamento de envios

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

Configuração inicial

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

Verificar sua configuração

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

Bibliotecas de cliente

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

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

Estruturas de dados

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

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

Elas também servem para estimar os intervalos dos motoristas e as paradas programadas ao longo do dia.

Veículos de entrega

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

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

Tarefas

Você atribui tarefas de acordo com o tipo de ação que um veículo realiza durante o dia:

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

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

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

Tarefas de envio

Criar tarefas para retirada e entrega de uma remessa e incluir as seguintes informações:

  • O local da retirada ou entrega.
  • Um número de rastreamento ou ID.
  • Um tempo de permanência para contabilizar o tempo adicional para concluir a tarefa, procurar estacionamento ou caminhar até o local de entrega.
  • Um ID de tarefa exclusivo. Consulte Diretrizes do ID da tarefa.

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

Android

iOS

Tarefas de indisponibilidade

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

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

  • A duração do intervalo.
  • O local do intervalo (opcional). Você não precisa informar um local específico, mas fazer isso fornece janelas de HEC mais precisas ao longo do dia.

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

Android

iOS

Tarefas de parada agendadas

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

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

Android

iOS

Diretrizes do ID da tarefa

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

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

Veja a seguir alguns exemplos de bons IDs de tarefas:

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

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

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

Mais recursos

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

Vida útil de um veículo

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

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

Use IDs exclusivos para cada veículo. Não reutilize um ID de veículo, a menos que não haja tarefas ativas para o veículo original.

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

  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.

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 de veículos usam o RouteTravelMode correspondente ao 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 nos atributos, porque esse campo pode ficar visível para os usuários.

O ciclo de uma tarefa

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

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

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

Diretrizes da tarefa

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

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

Quando o veículo da tarefa conclui a parada:

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

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

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

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

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

Atributos da tarefa

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

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

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

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

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

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

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

  • Um motorista se aproxima de uma parada de entrega. O aplicativo do driver envia a localização ao Fleet Engine.
  • O Fleet Engine envia a localização do dispositivo para a biblioteca de rastreamento, que é usada pelo app de consumidor para alertá-lo sobre a proximidade do pacote.
  • Depois que o motorista conclui o envio, ele clica no botão "Envio entregue" no aplicativo do motorista.
  • A ação "Envio entregue" envia as informações para seu sistema de back-end, que executa as etapas necessárias de validação e verificação da empresa.
  • O sistema confirma a tarefa como CONCLUÍDA e atualiza o Fleet Engine usando a API Deliveries.

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

Como usar a API Deliveries

Gerenciar tokens do cliente

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

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

  2. Forneça um token de escopo limitado ao aplicativo do driver. Este escopo só permite atualizar a localização do dispositivo no Fleet Engine.

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

Outros papéis da conta de serviço

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

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

Modelar um dia de trabalho

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

TempoAtividadeModelagem
Até 24 horas antes do início do dia O agente atribui remessas a veículos ou rotas de entrega. É possível criar tarefas para entregas de remessas, retiradas, quebras e outras no Fleet Engine com antecedência. Por exemplo, é possível criar uma tarefa de retirada, tarefa de entrega de envio, indisponibilidade programada ou parada programada.

Atribua tarefas a um veículo depois que o conjunto de pacotes de entrega e a ordem em que precisam ser entregues forem finalizados.
Início do dia O motorista começa o dia no depósito fazendo login no app dele. Inicialize a API Delivery Driver. Crie o veículo de entrega no Fleet Engine conforme necessário.
O motorista carrega as remessas no veículo de entrega, digitalizando as remessas. Se as tarefas de entrega de remessa não foram criadas com antecedência, crie tarefas de entrega de remessa no momento da leitura.
O motorista confirma a ordem das tarefas a serem realizadas. Se elas não foram criadas com antecedência, crie tarefas de retirada de remessa, indisponibilidade programada e paradas programadas.
O driver sai do depósito e realiza a confirmação para o próximo número de tarefas a serem concluídas. Atribua todas as tarefas ou um subconjunto de tarefas ao veículo, confirmando a ordem de conclusão.
Motorista entrega uma encomenda Depois de chegar à parada de entrega, realize ações relacionadas a um veículo que chega a uma parada. Depois de entregar a remessa, feche a tarefa de entrega e, se quiser, o status da remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e ao viajar até a próxima parada.
O motorista encontra um veículo alimentador para transferir outros envios para o veículo de entrega. O ponto de encontro para uma baldeação entre o alimentador e os veículos de entrega precisa ser modelado como uma parada programada.

Depois de transferir e verificar as remessas, crie tarefas de entrega, caso elas ainda não tenham sido criadas. Em seguida, atualize a ordem de conclusão da tarefa atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
O motorista recebe uma notificação de pedido de retirada. Depois de aceitar o pedido de retirada, crie uma tarefa de retirada. Em seguida, atualize a ordem de execução atribuindo tarefas a um veículo e atualizando a ordem das tarefas.
Pico Motorista faz uma pausa para o almoço. Se um local estiver associado à tarefa de indisponibilidade, trate-o como qualquer outra tarefa. Realizar ações relacionadas a um veículo chegando em uma parada, o veículo conclui uma parada e o veículo até a próxima parada.

Caso contrário, nenhuma outra ação será necessária até o fim do intervalo. Remova a tarefa confirmando as próximas e restantes e atualizando a ordem das tarefas.
Motorista pega uma remessa. Isso é modelado como uma parada de entrega. Realizar ações relacionadas a um veículo que chega a uma parada e fechar uma tarefa e, opcionalmente, armazenar o status da remessa e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada. Observação: para garantir o faturamento correto, todas as retiradas precisam ter uma tarefa de entrega correspondente. Se a retirada precisar ser entregue em outro local no mesmo trajeto do motorista naquele dia, recomendamos modelar essa tarefa de entrega como qualquer outra tarefa de entrega no trajeto. Se o motorista estiver trazendo a coleta de volta para o depósito, recomendamos criar uma tarefa de entrega no destino do depósito.
O motorista faz uma parada programada para retirar as encomendas em uma caixa de depósito. Ele é modelado como qualquer outro ponto de embarque. Realizar ações relacionadas a um veículo chegando a uma parada e fechar uma tarefa. Depois de concluir todas as tarefas e começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada.
O motorista recebe uma notificação sobre uma remessa sendo desviada para um local alternativo. Defina o status da tarefa de entrega original como CONCLUÍDA e crie uma nova tarefa de entrega para o novo local. Para mais informações, consulte Redirecionar uma remessa.
O motorista tentou entregar um pacote, mas não conseguiu. Isso é modelado de maneira semelhante a uma parada de entrega bem-sucedida, marcando a tarefa de entrega como concluída. Realize ações relacionadas a um veículo que chega a uma parada. Depois de não entregar a remessa, feche a tarefa e, opcionalmente, armazene o status da remessa e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada.
O motorista foi notificado para reter (não entregar) uma remessa. Depois que a notificação for recebida e confirmada, defina o status da tarefa como CONCLUÍDA.
O motorista foi notificado para entregar determinada remessa em seguida, alterando a ordem de entrega confirmada. Atualizar a ordem das tarefas.
O motorista escolhe entre entregar uma encomenda fora de ordem. Atualize a ordem das tarefas e continue normalmente.
o motorista entrega várias encomendas para um único local. Isso é modelado de forma semelhante a uma única parada de entrega de remessa. Depois de chegar à parada, realize ações relacionadas a um veículo chegando a uma parada. Depois de entregar cada remessa, feche cada tarefa e, opcionalmente, o status da remessa da loja e outras metainformações. Depois de concluir todas as tarefas e antes de começar a dirigir até a próxima parada, realize ações relacionadas a o veículo conclui uma parada e o veículo até a próxima parada.
Fim do dia O motorista volta ao depósito. Se o motorista retornar ao depósito com encomendas coletadas durante o trajeto, você também precisará criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. Para fazer isso, modele o depósito como qualquer outra parada de entrega. Se o depósito não estiver sendo usado como uma parada de entrega, ele ainda poderá ser modelado como uma parada programada. Com eles, os motoristas podem ver o trajeto de volta ao depósito, além de mostrar o horário estimado de chegada.

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

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

  1. A opção mais simples é usar o SDK do Driver, Android ou iOS.
  2. Use código personalizado. Isso é útil se os locais forem realçados pelo seu back-end ou se você usa dispositivos que não são Android ou iOS.

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

Paradas de veículos e locais de entrega

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

O local de entrega é o local onde a remessa será entregue ou retirada. Para ir e voltar do local de entrega, pode ser necessário caminhar da parada do veículo.

Por exemplo, quando um motorista está entregando uma remessa em uma loja de um shopping, o veículo de entrega para no estacionamento do shopping próximo à entrada mais próxima da loja. Esta é a parada do veículo. Em seguida, o motorista caminha da parada do veículo até o local dentro do shopping onde a loja está localizada. Este é o local de entrega.

Para ter a melhor experiência de rastreamento de frete para seus usuários, considere como as tarefas de envio são atribuídas às paradas de veículos e lembre-se de que o número de paradas de veículos restantes para tarefas de envio é relatado ao usuário para ajudá-lo a visualizar o progresso do envio.

Por exemplo, se um motorista está fazendo muitas entregas em um único escritório, considere atribuir todas as tarefas de entrega a uma única parada de veículo. Se cada tarefa de entrega for atribuída à própria parada do veículo, sua experiência de rastreamento de envio será menos útil para os usuários, porque o rastreamento só estará disponível quando o veículo estiver dentro de um número limitado de paradas antes do destino. Ter muitas paradas de veículos concluídas em um curto período não dá ao usuário muito tempo para acompanhar o progresso da entrega.

Usar SDKs para dispositivos móveis

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

Inicializar a API Delivery Driver

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

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

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

Casos de uso

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

Identificadores exclusivos de entidade

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

Criar um veículo

É possível criar um veículo a partir do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST.

gRPC

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

Ao criar um DeliveryVehicle, você tem a opção de especificar estes campos:

  • Atributos
  • LastLocation
  • Tipo

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

Para criar um veículo sem definir campos opcionais, deixe o campo DeliveryVehicle sem definição no CreateDeliveryVehicleRequest.

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

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    String parent = "providers/" + PROJECT_ID;
    DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
      .addAttributes(DeliveryVehicleAttribute.newBuilder()
        .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
      .build();

    // Vehicle request
    CreateDeliveryVehicleRequest createVehicleRequest =
      CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setParent(parent)
          .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
          .setDeliveryVehicle(vehicle)
          .build();

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

    try {
      DeliveryVehicle createdVehicle =
        deliveryService.createDeliveryVehicle(createVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Para criar um veículo usando um ambiente de servidor, faça uma chamada HTTP REST para CreateDeliveryVehicle:

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

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

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

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

  • atributos
  • lastLocation
  • Tipo

Comando curl de exemplo:

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

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

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

Comando curl de exemplo:

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

Criar uma tarefa de retirada de remessa

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefa no seu sistema, poderá gerar um identificador universal exclusivo (UUID, na sigla em inglês).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Criar uma tarefa de entrega

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa. Ele não pode ser o número de rastreamento do envio. Se você não tiver IDs de tarefa no seu sistema, poderá gerar um identificador universal exclusivo (UUID, na sigla em inglês).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Criar tarefas em lote

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

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para criar duas tarefas, uma para entrega e outra para retirada no mesmo local:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para criar uma tarefa de entrega e retirada em um ambiente de servidor, faça uma chamada HTTP REST para BatchCreateTasks:

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

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

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

  • Campos obrigatórios:

    CampoValor
    solicita Matriz<CreateTasksRequest>

  • Campos opcionais:

    CampoValor
    cabeçalho "DeliveryRequestHeader"

Cada elemento CreateTasksRequest em requests precisa passar as mesmas regras de validação que uma solicitação CreateTask, com exceção de que os campos parent e header são opcionais. Se definidos, eles precisam ser idênticos aos respectivos campos no nível superior BatchCreateTasksRequest. Consulte Criar uma tarefa de retirada de remessa e Criar uma tarefa de entrega de remessa para conferir as regras de validação específicas de cada uma.

Para mais informações, consulte a documentação de referência da API para BatchCreateTasks (gRPC, REST).

Comando curl de exemplo:

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

Indisponibilidade programada

É possível criar uma tarefa que indica indisponibilidade (por exemplo, para motoristas ou reabastecimento de veículos) usando o SDK do driver ou de um ambiente de servidor usando gRPC ou REST. Uma tarefa de indisponibilidade programada não pode incluir um ID de acompanhamento. Você também pode informar um local.

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

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

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

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

REST

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

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

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

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    CampoValor
    plannedLocation O local do intervalo, se precisar ser feito em um local específico.

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

Comando curl de exemplo:

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

Paradas programadas

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

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

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

REST

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

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

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

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

Definir a janela de tempo desejada

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

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

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir uma janela de horário da tarefa:

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa.

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

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

A visibilidade dos dados na biblioteca Shipment Tracking e dos dados retornados de uma chamada para GetTaskTrackingInfo podem ser controladas por tarefa configurando um TaskTrackingViewConfig na tarefa. Consulte Tarefas ativas do veículo para mais informações. Isso pode ser feito ao criar ou atualizar a tarefa. Veja a seguir um exemplo de atualização da tarefa com essa configuração:

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa.

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

Atribuir tarefas a um veículo

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

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

Atualizar a ordem das tarefas

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

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

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

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

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

Para atualizar a ordenação de tarefas de um veículo em um ambiente de servidor, faça uma chamada REST HTTP para UpdateDeliveryVehicle:

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

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

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

O veículo está a caminho da próxima parada

O motor da frota precisa ser notificado quando um veículo sai de uma parada ou inicia a navegação. Notifique o Fleet Engine a partir do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte da verdade.

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

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

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

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

  • Campo obrigatório:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

Atualizar local do veículo

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

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

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

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

  • Campo obrigatório:

    CampoValor
    lastLocation.supplementalLocation O local do veículo.
    lastLocation.supplementalLocationTime O último carimbo de data/hora conhecido do veículo estava nesse local.
    lastLocation.supplementalLocationSensor Precisa ser preenchido com CUSTOMER_ autopLIED_LOCATION.

  • Campos opcionais:

    CampoValor
    lastLocation.supplementalLocationAccuracy Precisão do local informado, em metros.

Comando curl de exemplo:

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

O veículo chega a uma parada

O motor da frota precisa ser notificado quando um veículo chega a uma parada. Notifique o Fleet Engine a partir do SDK do Driver ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte da verdade.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

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

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

REST

Para notificar o Fleet Engine sobre a chegada de um veículo em uma parada de um ambiente de servidor, faça uma chamada HTTP REST para UpdateDeliveryVehicle:

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

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

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

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

  • Campos obrigatórios:

    CampoValor
    remainingVehicleJourneySegments A parada em que você chegou com o estado definido como State.ARRIVED, seguido por uma lista de paradas de veículos restantes com os estados marcados como State.NEW.

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

O veículo faz uma parada

O motor da frota precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada sejam definidas no estado FECHADO. É possível notificar o Fleet Engine pelo SDK do Driver ou por um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

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

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhuma

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

Comando curl de exemplo:

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

Atualizar uma tarefa

A maioria dos campos de tarefas é imutável. No entanto, é possível modificar o estado, o resultado da tarefa, o horário e o local do resultado da tarefa e os atributos atualizando diretamente a entidade da tarefa. Por exemplo, nos casos em que uma tarefa não foi atribuída a um veículo, você pode encerrá-la atualizando o estado diretamente.

gRPC

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

REST

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

Encerrar uma tarefa

Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada onde a tarefa ocorre ou remova-o da lista de paradas de veículos. Para fazer isso, defina a lista das paradas restantes do mesmo modo que ao atualizar a ordem das tarefas de um veículo.

Se uma tarefa ainda não tiver sido atribuída a um veículo e precisar ser fechada, atualize-a para o estado FECHADO. Entretanto, você não pode reabrir uma tarefa FECHADA.

O encerramento de uma tarefa não indica sucesso ou falha. Isso indica que a tarefa não é mais considerada em andamento. No rastreamento de remessa, é importante indicar o resultado real de uma tarefa para que o resultado da 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:

    CampoValor
    state State.CLOSED

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Definir o resultado da tarefa e o local do resultado

O encerramento de uma tarefa não indica sucesso ou falha, mas sim que a tarefa não é mais considerada em andamento. Para o rastreamento de remessa, é importante indicar o resultado real de uma tarefa para que um resultado de entrega possa ser mostrado e que o faturamento dos serviços seja adequado. Depois de definido, não é possível mudar o resultado da tarefa. No entanto, é possível modificar o horário e o local do resultado da tarefa depois que eles forem definidos.

As tarefas no estado FECHADO podem ter o resultado definido como SUCCEEDED ou FAILED. O Fleet Engine cobra apenas tarefas de entrega com o estado SUCCEEDED.

Ao marcar o resultado de uma tarefa, o Fleet Engine preenche automaticamente o local de resultado da tarefa com o último local conhecido do veículo. É possível substituir esse comportamento.

gRPC

Você tem a opção de definir o local de resultado da tarefa ao definir o resultado. Isso impede que o Fleet Engine o defina como o padrão da última localização do veículo. Também é possível substituir o local de resultado da tarefa definido pelo Fleet Engine mais tarde. O Fleet Engine nunca substitui um local de resultado de tarefa fornecido por você. Não é possível definir um local de resultado para uma tarefa que não tenha um conjunto de resultados de tarefa. É possível definir o resultado da tarefa e o local dos resultados na mesma solicitação.

O exemplo a seguir mostra como usar a biblioteca Java gRPC para definir um resultado de tarefa como SUCCEEDED e definir o local em que a tarefa foi concluída:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

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

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

REST

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

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

<id> é um identificador exclusivo da tarefa.

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

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

  • Campos obrigatórios:

    CampoValor
    taskOutcome Result.SUCCEEDED ou Outcome.FAILED
    taskOutcomeTime O carimbo de data/hora de quando o resultado da tarefa foi definido (do provedor). Esse é o momento em que a tarefa foi concluída.

  • Campos opcionais:

    CampoValor
    taskOutcomeLocation O local em que a tarefa foi concluída. O padrão do Fleet Engine é a última localização do veículo, a menos que seja substituído manualmente pelo provedor.

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

Comando curl de exemplo:

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

Redirecionar uma remessa

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

Usar alimentador e veículos de entrega

Se você usa veículos alimentadores para transportar remessas para veículos de entrega durante todo o dia, modele a transferência das encomendas como uma tarefa de parada programada para o veículo de entrega. Para garantir o rastreamento preciso da localização, só atribua uma tarefa de entrega para uma remessa transferida depois que ela for carregada no veículo de entrega. Para mais informações, consulte parada programada.

Status do envio da loja e outras informações meta

Quando uma tarefa de remessa é concluída, o estado e o resultado da tarefa são registrados nela. No entanto, você pode querer atualizar outras metainformações específicas do envio. Para armazenar outras metainformações que possam ser referenciadas fora do serviço do Fleet Engine, use o "tracking_id" associado à tarefa como uma chave em uma tabela externa.

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

Procurar um veículo

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

REST

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

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

<id> é um identificador exclusivo da tarefa.

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

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

O corpo da solicitação precisa estar vazio.

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

Comando curl de exemplo:

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

Procurar uma tarefa

É possível pesquisar uma tarefa em um ambiente de servidor usando gRPC ou REST. O SDK do Driver não oferece suporte à procura de uma tarefa.

gRPC

O exemplo a seguir mostra como usar a biblioteca Java gRPC para procurar uma tarefa:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para procurar uma tarefa em um ambiente de servidor, faça uma chamada HTTP REST para GetTask:

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

<id> é um identificador exclusivo da tarefa.

<taskId> é o ID da tarefa a ser pesquisada.

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

O corpo da solicitação precisa estar vazio.

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

Comando curl de exemplo:

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

Pesquisar informações de tarefas de envio pelo ID de rastreamento

É possível procurar informações sobre as tarefas de frete das maneiras a seguir, cada uma com uma finalidade específica:

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

Esta seção discute a pesquisa de informações da tarefa usando um ID de acompanhamento. Para procurar uma tarefa pelo ID, acesse Procurar uma tarefa.

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

Requisitos de pesquisa

  • As informações de envio fornecidas por um ID de rastreamento estão em conformidade com as regras de visibilidade estabelecidas em Controlar a visibilidade dos locais rastreados.

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

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

Pesquisas com Java usando gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Pesquisas usando HTTP

Para procurar uma tarefa de envio em um navegador, faça uma chamada HTTP REST para GetTaskTrackingInfo:

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

<tracking_id> é o ID de acompanhamento associado à tarefa.

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

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

Comando curl de exemplo:

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

Listar tarefas

É possível listar tarefas de um ambiente de servidor ou navegador. O SDK do Driver não permite a listagem de tarefas.

Para listar tarefas, é preciso ter amplo acesso a elas. A listagem de tarefas é destinada apenas a usuários confiáveis. Use o leitor da frota de entrega ou tokens de autenticação de superusuário de entrega ao fazer solicitações de tarefas de lista.

As tarefas listadas têm os seguintes campos editados:

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

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

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

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

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

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

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

As listas de tarefas são paginadas. Um tamanho de página pode ser especificado em solicitações de tarefas de lista. Se um tamanho de página for especificado, o número de tarefas retornadas não será maior que o tamanho especificado. Se nenhum tamanho de página estiver presente, um padrão razoável será usado. Se o tamanho da página solicitado exceder um valor máximo interno, o máximo interno será usado.

Uma lista de tarefas pode incluir um token para ler a próxima página de resultados. Use o token da página com uma solicitação idêntica à solicitação anterior para recuperar a próxima página de tarefas. Quando o token da página retornado está vazio, não há mais tarefas disponíveis para recuperação.

gRPC

O exemplo a seguir mostra como usar a biblioteca gRPC do Java para listar tarefas para um deliveryVehicleId e um atributo de tarefa. Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que nenhuma tarefa está associada ao deliveryVehicleId fornecido.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Para listar tarefas de um navegador, faça uma chamada HTTP REST para ListTasks:

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

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

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

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

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

Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que nenhuma tarefa foi encontrada atendendo aos critérios de filtro especificados.

Comando curl de exemplo:

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

Listar veículos de entrega

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

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

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

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

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

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

As listas de veículos de entrega são paginadas por padrão usando um tamanho de página razoável. Se você especificar um tamanho de página, a solicitação retornará apenas o número de veículos especificado pelo limite ou menos. Se o tamanho da página solicitado exceder um valor máximo interno, o máximo interno será usado. Os tamanhos de página padrão e máximo são 100 veículos.

Uma lista de veículos de entrega pode incluir um token para ler a próxima página de resultados. Um token de página só está presente em uma resposta quando mais páginas de veículos de entrega estão disponíveis para recuperação. Para recuperar a próxima página de tarefas, use o token de página com uma solicitação idêntica à solicitação anterior.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

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

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

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

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

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

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

Uma resposta bem-sucedida ainda pode estar vazia. Quando isso acontece, significa que nenhum veículo de entrega foi encontrado atendendo à consulta de filtro e à janela de visualização especificadas.

Comando curl de exemplo:

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

Rastreamento de envios

Há duas opções para usar a API Fleet Engine Deliveries:

  • 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 de rastreamento de envio animada e personalizável no seu aplicativo da Web ou para dispositivos móveis.

  • Implemente seu próprio rastreamento de remessa sobre a API Fleet Engine Deliveries.

A chave é procurar tarefas de envio 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 destinatário. Todas as outras informações nas respostas são editadas. Você é responsável pela autenticação dos usuários finais. Além disso, as informações de local são filtradas com base na tarefa que já está sendo realizada. Durante uma tarefa de indisponibilidade, nenhuma informação de localização é compartilhada com um usuário final.

Geração de registros

É possível configurar o Fleet Engine para enviar registros de RPC para o Cloud Logging. Para mais informações, consulte Logging.

Papéis e tokens de autorização

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

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

Solução de problemas comuns

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

Resiliência

O Fleet Engine não é considerado uma fonte da verdade. Você é responsável por restaurar o estado do sistema, se necessário, sem depender do Fleet Engine.

Estado perdido no Fleet Engine

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

No cenário extremamente improvável de uma falha catastrófica do Fleet Engine, talvez seja necessário recriar a maioria ou todos os veículos e tarefas. Se a taxa de criação ficar muito alta, algumas solicitações poderão falhar novamente devido a problemas de cota, já que as verificações de cota estão em vigor para evitar ataques de negação de serviço (DOS). Nesse caso, diminua a taxa de recriação usando uma estratégia de espera para novas tentativas.

Estado perdido no app do motorista

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

Perguntas frequentes

E se um motorista parar em uma tarefa fora de ordem?

Nesse caso, primeiro atualize a ordem das tarefas e prossiga normalmente, marcando a chegada na parada, a conclusão da tarefa e outros detalhes. Se você não fizer isso, o sistema poderá ficar inconsistente, os ETAs poderão ficar incorretos e erros inesperados poderão ser informados.