Comece a usar o Fleet Engine para rastreamento de envios

Modele as atividades da sua frota na primeira e última milha de entregas com a API Fleet Engine Deliveries. Você pode usar essa API com o SDK do Driver para Android e iOS, ou diretamente usando chamadas HTTP REST ou gRPC.

Configuração inicial

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

Verificar sua configuração

Depois de criar as contas de serviço, verifique se a configuração foi concluída e criar um veículo de entrega. Verificando sua configuração imediatamente garante a solução de problemas de autorização comuns que podem surgir configurando seu projeto. Há duas maneiras de verificar a configuração:

Bibliotecas de cliente

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

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

Estruturas de dados

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

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

Você também usa tarefas para modelar as pausas para motoristas e paradas programadas ao longo do dia.

Veículos de entrega

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

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

Tarefas

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

  • Para retiradas e entregas, atribua Tarefas de envio.
  • Quando os motoristas não estão disponíveis, como pausas obrigatórias, atribuir Tarefas de indisponibilidade.
  • Para tarefas que não são como motorista em caixas de depósito ou em locais de clientes, atribua Tarefas com paradas programadas.

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

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

Tarefas de envio

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

  • O local da retirada ou entrega.
  • Um número ou ID de rastreamento.
  • Um tempo de espera para contabilizar um tempo adicional para concluir a tarefa; procure para estacionar ou caminhar até o local de transferência.
  • Um ID de tarefa exclusivo. Consulte as diretrizes de IDs de tarefas.

Para mais informações, consulte os tópicos a seguir:

Android

iOS

Tarefas de indisponibilidade

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

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

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

Para mais informações, consulte os tópicos a seguir:

Android

iOS

Tarefas com paradas programadas

Criar tarefas de paradas programadas para determinar as paradas necessárias para um veículo de entrega fazer. Por exemplo, crie uma tarefa de parada programada para um horário programado parada de coleta em um local específico, independentemente de outras entregas ou retiradas no mesmo local. Também é possível criar tarefas com paradas programadas para coletas de caixas de depósito ou transferências de modelos alimentadores e veículos ou paradas em centros e pontos de serviço.

Para mais informações, consulte os tópicos a seguir:

Android

iOS

Diretrizes do ID da tarefa

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

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

Confira abaixo alguns exemplos de IDs de tarefas adequados:

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

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

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

Mais recursos

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

Vida útil de um veículo

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

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

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

O Fleet Engine exclui automaticamente DeliveryVehicle objetos que não foram foi atualizado usando UpdateDeliveryVehicle após sete dias. As recomendações para manter um veículo disponível no Fleet Engine é atualizar a localização dele em intervalos regulares. Atualizações para a maioria dos outros campos no DeliveryVehicle entidade também vai prolongar a vida útil, desde que o novo valor do campo seja diferente do que já existe.

Para saber se um veículo existe:

  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 Uma enumeração Category pode ser especificada como AUTO, TWO_WHEELER, BICYCLE ou PEDESTRIAN. Se você não definir o campo, o padrão será AUTO.

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

Atributos do veículo

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

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

A vida de uma tarefa

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

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

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

Diretrizes de tarefas

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

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

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

  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 indica o resultado da tarefa e, o status da tarefa será definido automaticamente como FECHADA. Para mais informações, consulte Rastrear envios com a biblioteca JavaScript Shipment Tracking.

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

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

Atributos da tarefa

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

Não inclua informações de identificação pessoal (PII) ou outros dados sensíveis informações nos atributos, já que esses atributos podem ser visíveis aos usuários.

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

Lembrete: seu sistema interno atua como a fonte confiável dos dados que o A API Fleet Engine Deliveries é aumentada por você.

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

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

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

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

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

Como usar a API Deliveries

Gerenciar tokens do cliente

Atualizações de localização originadas do aplicativo do motorista e enviadas diretamente ao Fleet Engine exigem tokens de autorização. Esta é a abordagem recomendada para gerenciar as atualizações do cliente no Fleet Engine:

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

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

Com essa abordagem, as chamadas provenientes de dispositivos móveis ambientes de baixa confiança, siga as princípio de privilégio mínimo.

Outros papéis da conta de serviço

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

Para mais informações sobre os usos das funções de motorista confiáveis e não confiáveis, consulte Configuração do projeto do Cloud.

Planeje um dia de trabalho

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

TempoAtividadeModelagem
Dentro de 24 horas a partir do início do dia O agente atribui remessas a veículos ou rotas de entrega. É possível criar tarefas para entregas, retiradas, intervalos e outros no Fleet Engine com antecedência. Por exemplo, é possível criar tarefa de coleta de remessa, tarefa de entrega de pedidos, indisponibilidade programada; parada programada.

Atribuir tarefas a um veículo quando o conjunto de pacotes de entrega e a ordem em que devem ser entregues estão finalizadas.
Início do dia O motorista começa o dia no depósito fazendo login no app. Inicialize a API Delivery Driver. Crie o veículo de entrega no Fleet Engine, conforme necessário.
O motorista carrega as remessas no veículo de entrega, digitalizando as remessas. Se as tarefas de entrega da remessa não foram criadas antecipadamente, criar tarefas de entrega de frete no momento da verificação.
O motorista confirma a ordem das tarefas a serem realizadas. Se elas não tiverem sido criadas com antecedência, crie tarefas de retirada no frete indisponibilidade programada; paradas programadas.
O driver sai do depósito e se compromete com o próximo número de tarefas a serem concluído. Atribuir todas as tarefas ou um subconjunto de tarefas ao veículo, confirmando o pedido de conclusão.
O motorista entrega uma remessa. Após chegar na parada de entrega, realize as ações relacionadas a um veículo chegando a uma parada. Depois de entregar o pacote, feche o tarefa de entrega e, como opção, status de remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes começar a dirigir até a próxima parada, realizar ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada.
O motorista encontra um veículo alimentador para transferir remessas adicionais para o veículo de entrega. Ponto de encontro para uma baldeação entre o feeder e os veículos de entrega deve ser definida como uma parada programada.

Depois de transferir e escanear as remessas, crie tarefas de entrega caso ainda não tenham sido criados. Em seguida, atualize a conclusão da tarefa ordenar atribuindo tarefas a um veículo e atualizar a ordem das tarefas.
O motorista recebe uma notificação de um pedido de retirada. Depois de aceitar o pedido de retirada, criar uma tarefa de retirada de fretes. Em seguida, atualize a execução da tarefa ordenar atribuindo tarefas a um veículo e atualizar a ordem das tarefas.
Meio-dia Motorista faz uma pausa para o almoço. Se um local estiver associado à tarefa de indisponibilidade, trate-o como qualquer outra tarefa. Realizar ações relacionadas a um veículo chegar a uma parada, veículo conclui uma parada e veículo a caminho da próxima parada.

Caso contrário, nenhuma outra ação é necessária até o fim do intervalo. Remova a tarefa confirmando as tarefas seguintes e as restantes. Como atualizar a ordem das tarefas.
O motorista pega uma remessa. Isso é modelado como uma parada de entrega. Realizar ações relacionadas a um veículo chegando a uma parada fechar uma tarefa e, como opção, armazenar o status do envio e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada. Observação: para garantir o faturamento correto, todas as retiradas precisam ter um tarefa de entrega. Se a retirada for entregue em outro local no do mesmo trajeto do motorista naquele dia, recomendamos modelar essa tarefa de entrega como qualquer outra tarefa de entrega no trajeto. Se o motorista estiver trazendo o pedido de retirada para o depósito, recomendamos criar uma tarefa de entrega no depósito destino.
O motorista faz uma parada programada para retirar as remessas em uma caixa de depósito. Ela é modelada da mesma forma que qualquer outra parada de embarque. Realizar ações relacionadas a um veículo chegando a uma parada e encerrar uma tarefa. Depois de concluir todas as tarefas na parada e começando a dirigir até a próxima parada, realizar ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada.
O motorista recebe uma notificação de que uma remessa foi desviada para um local alternativo. Defina o status de entrega da remessa original como CONCLUÍDA e crie um novo tarefa de entrega da remessa para o novo local de entrega. Para mais informações, consulte Redirecionar uma remessa.
O motorista tentou entregar um pacote, mas não conseguiu. Isso é semelhante a uma interrupção de entrega, marcando o a tarefa de entrega como concluída. Realizar ações relacionadas a um veículo chegando a uma parada. Depois falha na entrega da remessa, fechar a tarefa e, opcionalmente, status de remessa da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada.
O motorista foi notificado para reter (não entregar) uma remessa. Após a notificação ser recebida e confirmada, defina o status da tarefa como CONCLUÍDA.
O motorista foi notificado para entregar determinada remessa em seguida, alterando o pedido de entrega confirmado. Atualizar a ordem das tarefas.
O motorista decide entregar uma remessa fora de ordem. Atualizar a ordem das tarefas e, em seguida, continue normalmente.
O motorista entrega várias encomendas para um único local. Isso é modelado de maneira semelhante a uma única parada de entrega de remessa. Após chegar na parada, realize as ações relacionadas a um vehicle chegando em uma parada. Depois de entregar cada remessa, feche cada tarefa e, opcionalmente, status de envio da loja e outras metainformações. Depois de concluir todas as tarefas na parada e antes de começar a dirigir até a próxima parada, realize ações relacionadas a veículo conclui uma parada e vehicle a caminho da próxima parada.
Fim do dia O motorista retorna ao depósito. Se o motorista retornar ao depósito com remessas retiradas durante o você também precisa criar e fechar cada pacote como uma tarefa de entrega para garantir o faturamento correto. Você pode fazer isso modelando o depósito como qualquer outra parada de entrega. Se o depósito não estiver sendo usado como parada de entrega, você ainda poderá, como opção, modelar o depósito como uma parada programada. Fazer um modelo da parada permite que os motoristas vejam o trajeto de volta à estação e mostrar o tempo estimado de chegada.

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

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

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

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

Paradas e locais de entrega de veículos

Uma parada de veículo é onde um veículo de entrega conclui uma tarefa de envio ou alguma outra tarefa. Ele é um ponto de acesso como uma plataforma de carregamento na via.

O local de entrega é o local em que o produto será entregue ou retirado. Pode ser necessário caminhar um pouco para ir e voltar do local de entrega na parada do veículo.

Por exemplo, quando um motorista entrega uma remessa de uma loja de um shopping, o veículo de entrega para no estacionamento do shopping perto a entrada mais próxima da loja. Esta é a parada do veículo. O motorista e depois caminha da parada de veículos até o local do shopping onde onde a loja está localizada. Esse é o local de entrega.

Para a melhor experiência de rastreamento de remessa para seus usuários, considere como as tarefas de remessa são atribuídas a paradas de veículos e tenha em mente que o número de as paradas restantes do veículo para as tarefas da remessa são informadas ao usuário para ajudar visualizar o progresso do envio.

Por exemplo, se um motorista está fazendo muitas entregas em um único prédio comercial, considere atribuir todas as tarefas de entrega a uma única parada de veículo. Se cada tarefa de entrega é atribuída a uma parada de veículo, a remessa experiência de acompanhamento seria menos útil para seus usuários, pois o acompanhamento é apenas disponível quando o veículo estiver dentro de um número limitado de paradas antes ao destino. Ter muitas paradas de veículos concluídas em um curto período não proporciona ao usuário muito tempo para acompanhar o progresso da entrega.

Usar os SDKs para dispositivos móveis

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

Inicializar a API Delivery Driver

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

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

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

Casos de uso

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

Identificadores exclusivos de entidade

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

Criar um veículo

Você pode criar um veículo no SDK do driver ou de um ambiente de servidor usando gRPC ou REST.

gRPC

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

Ao criar um DeliveryVehicle, também é possível especificar estes campos:

  • Atributos
  • LastLocation
  • Tipo

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

Para criar um veículo sem definir nenhum campo opcional, você pode deixar o Campo DeliveryVehicle não definido em CreateDeliveryVehicleRequest.

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo de um veículo de entrega na sua frota.

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

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

  • Atributos
  • lastLocation
  • tipo

Comando curl de exemplo:

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

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

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

Comando curl de exemplo:

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

Criar uma tarefa de retirada de frete

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa. Não pode ser o número de rastreamento para o envio. Se você não tem IDs de tarefas em seu sistema, pode gerar um identificador universalmente exclusivo (UUID).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Criar uma tarefa de entrega de remessa

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa. Não pode ser o número de rastreamento para o envio. Se você não tem IDs de tarefas em seu sistema, pode gerar um identificador universalmente exclusivo (UUID).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Tarefas de criação em lote

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

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

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

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

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

REST

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

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

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

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

  • Campos obrigatórios:

    CampoValor
    solicitações Matriz <CreateTasksRequest>

  • Campos opcionais:

    CampoValor
    cabeçalho `DeliveryRequestHeader`

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

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

Comando curl de exemplo:

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

Indisponibilidade programada

É possível criar uma tarefa indicando indisponibilidade (por exemplo, para motoristas quebras ou reabastecimento de veículos) da SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Uma tarefa de indisponibilidade programada não pode incluir um ID de acompanhamento. Também é possível informar um local.

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa. Se você não IDs de tarefas no sistema, é possível gerar um ID exclusivo (UUID).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    CampoValor
    plannedLocation Indica o local da pausa, caso ela precise ser realizada em um local específico.

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

Comando curl de exemplo:

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

Paradas programadas

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa. Se você não tiver IDs de tarefas no sistema, poderá gerar um identificador universalmente exclusivo (UUID).

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhum

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

Comando curl de exemplo:

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

Definir janela de tempo desejada

A janela de tempo desejada TimeWindow durante o qual a tarefa deve ser concluída. Por exemplo, se você comunicar uma a janela de tempo de entrega aos destinatários, use o intervalo de tempo para capturar a janela de tempo e gerar alertas ou analisar o pós-viagem desempenho usando o campo.

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

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é 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:

    • Nenhum

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

Comando curl de exemplo:

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

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

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é 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 Configuração para o rastreamento de tarefas que especifica quais elementos de dados que são visíveis para os usuários finais em quais circunstâncias.

  • Campos opcionais:

    • Nenhum

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

Comando curl de exemplo:

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

Atribuir tarefas a um veículo

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

Para transferir uma remessa de um veículo para outro, feche a tarefa original e recriá-la antes de atribuir o novo veículo a ela. Se você atualizar a tarefa ordenação para uma tarefa que já foi atribuída em um veículo diferente, ocorrerá um erro.

Atualizar a ordem das tarefas

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

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

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

Para transferir uma remessa de um veículo para outro, fechar a tarefa original e recriá-la antes de atribuir o novo veículo a ela. Se você atualizar a tarefa ordenação para uma tarefa que já foi atribuída em um veículo diferente, ocorrerá um erro.

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo de um veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhum

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

Comando curl de exemplo:

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

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

O Fleet Engine precisa ser notificado quando um veículo sai de uma parada ou começa navegação. É possível notificar o Fleet Engine pelo SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

gRPC

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

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.

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

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

  • Campo obrigatório:

    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:

    • Nenhum

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

Comando curl de exemplo:

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

Atualizar localização do veículo

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo do veículo de entrega na sua frota ou se você pretende atualizar o local. É o identificador que especificado ao criar o veículo.

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

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

  • Campo obrigatório:

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

  • Campos opcionais:

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

Comando curl de exemplo:

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

O veículo chega a uma parada

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.

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

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

  • Campos obrigatórios:

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

  • Campos opcionais:

    • Nenhum

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

Comando curl de exemplo:

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

O veículo conclui uma parada

O Fleet Engine precisa ser notificado quando um veículo conclui uma parada. Isso faz com que todas as tarefas associadas à parada a serem definidas para o estado CLOSED. Você pode notifique o Fleet Engine pelo SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST. Não use os dois métodos para evitar disputas e manter uma única fonte de verdade.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo do veículo de entrega na sua frota. para o qual você pretende atualizar a ordem das tarefas. É o identificador que especificado ao criar o veículo.

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

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

  • Campos obrigatórios:

    CampoValor
    remaining_vehicle_journey_segments A parada concluída não deve mais estar na lista de paradas de veículos restantes.

  • Campos opcionais:

    • Nenhum

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

Comando curl de exemplo:

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

Atualizar uma tarefa

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

gRPC

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

REST

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

Fechar uma tarefa

Para fechar uma tarefa atribuída a um veículo, notifique o Fleet Engine que o veículo concluiu a parada em que a tarefa ocorre ou removê-lo da lista de paradas de veículos. Para fazer isso, você pode definir a lista de o veículo restante para, assim como ao atualizar a ordem das tarefas; para um veículo.

Se uma tarefa ainda não tiver sido atribuída a um veículo e precisar ser fechada, atualize a tarefa para o estado CLOSED. No entanto, não é possível reabrir uma tarefa CLOSED.

O fechamento de uma tarefa não indica sucesso ou falha. Ele indica que o tarefa não é mais considerada em andamento. Para rastreamento de remessas, é importante indicar o resultado real de uma tarefa para que uma entrega pode ser mostrado.

gRPC

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

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

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

REST

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

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

&lt;id&gt; é 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
    estado State.CLOSED

  • Campos opcionais:

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

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

Comando curl de exemplo:

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

Definir o resultado da tarefa e o local dos resultados

O encerramento de uma tarefa não indica sucesso ou falha, mas indica que a tarefa não é mais considerada em andamento. Para rastreamento de remessas, é importante indicar o resultado real de uma tarefa para que o resultado da entrega pode ser mostrado e há cobrança adequada pelos serviços. Depois de definido, não é possível mudar o resultado da tarefa. No entanto, é possível modificar o horário e o local do resultado da tarefa depois de terem sido definidos.

Tarefas que estão no estado FECHADO podem ter seus resultados definidos como CONCLUÍDA ou COM FALHA. O Fleet Engine cobra apenas as tarefas de entrega com estado de CONCLUÍDA.

Ao marcar o resultado de uma tarefa, o Fleet Engine preenche automaticamente o local do resultado da tarefa com a última localização conhecida do veículo. Você pode substituir esse comportamento.

gRPC

Você tem a opção de definir o local do resultado da tarefa ao definir o resultado. Definir o local impede que o Fleet Engine o configure para o padrão da última localização do veículo. Também é possível substituir o local do resultado da tarefa do Fleet Engine definidos posteriormente. O Fleet Engine nunca substitui um local de resultado de tarefa que você fornece. Não é possível definir um local de resultados de tarefa para uma tarefa que não tem um conjunto de resultados de tarefa. É possível definir o resultado da tarefa e local do resultado da tarefa dentro da mesma solicitação.

O exemplo a seguir mostra como usar o Biblioteca Java gRPC para definir o resultado de uma tarefa como CONCLUÍDO e definir o local onde a tarefa foi concluído:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; é 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 Outcome.SUCCEEDED ou Outcome.FAILED

  • Campos opcionais:

    CampoValor
    taskOutcomeLocation O local em que a tarefa foi concluída. Se não for definido, o Fleet Engine o padrão é a última localização do veículo.
    taskOutcomeTime O carimbo de data/hora em que a tarefa foi concluída.

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

Comando curl de exemplo:

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

Redirecionar uma remessa

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

Usar alimentador e veículos de entrega

Se você usa veículos alimentadores para transportar remessas para veículos de entrega ao longo do dia, modelar a transferência de remessas como uma tarefa de parada programada para o veículo de entrega. Para garantir um rastreamento de localização preciso, atribua uma tarefa de entrega para uma remessa transferida depois que ela é carregada na veículo de entrega. Para mais informações, consulte parada programada.

Armazenar status de envio e outras metainformações

Quando uma tarefa de remessa é concluída, o estado da tarefa e o resultado são registrados na tarefa. No entanto, convém atualizar outras metainformações específicas da remessa. Para armazenar outras metainformações que você pode referência fora do serviço do Fleet Engine, use o "tracking_id" associado com a tarefa como uma chave em uma tabela externa.

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

Procurar um veículo

Você pode procurar um veículo no SDK do Driver, ou de um ambiente de servidor usando gRPC ou REST.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa.

&lt;vehicleId&gt; é o ID do veículo a ser pesquisado.

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

O corpo da solicitação precisa estar vazio.

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

Comando curl de exemplo:

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

Procurar uma tarefa

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

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

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

&lt;id&gt; é um identificador exclusivo da tarefa.

&lt;taskId&gt; é o código da tarefa a ser pesquisada.

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

O corpo da solicitação precisa estar vazio.

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

Comando curl de exemplo:

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

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

Você pode procurar informações sobre as tarefas de remessa das seguintes maneiras: cada uma com uma finalidade diferente:

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

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

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

Requisitos de pesquisa

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

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

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

Pesquisas com Java usando gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Pesquisas usando HTTP

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

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

&lt;tracking_id&gt; é o ID de acompanhamento associado à tarefa.

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

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

Comando curl de exemplo:

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

Listar tarefas

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

A listagem de tarefas solicita amplo acesso às tarefas. A listagem de tarefas é destinada apenas a usuários confiáveis. Usar o leitor de frota de entrega ou a autenticação de superusuário de entrega Tokens ao fazer solicitações de tarefas de lista.

As tarefas listadas têm os seguintes campos encobertos:

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

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

  • Atributos
  • delivery_vehicle_id
  • estado
  • planned_location
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • tracking_id
  • tipo

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

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

Acesse AIP-160 para ver a lista completa de consultas de filtro operadores.

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

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

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

gRPC

O exemplo a seguir mostra como usar o Biblioteca Java gRPC para listar tarefas para um deliveryVehicleId e um atributo de tarefa. Um bem-sucedido a resposta poderá ficar em branco. Uma resposta vazia indica que não há Tarefas associou o deliveryVehicleId fornecido.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

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

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

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

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

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

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

Uma resposta bem-sucedida ainda pode estar vazia. Uma resposta vazia indica que não foram encontradas tarefas que atendem aos critérios de filtro especificados.

Comando curl de exemplo:

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

Listar veículos de entrega

É possível listar veículos de entrega de um ambiente de servidor ou navegador. O motorista O SDK não aceita a listagem de veículos de entrega.

A listagem de veículos de entrega solicita amplo acesso a veículos de entrega e é destinados apenas a usuários confiáveis. Usar Leitor de frota de entrega ou Super Entrega Tokens de autenticação do usuário ao fazer solicitações de veículos de entrega de listas.

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

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

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

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

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

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

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

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

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

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

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

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

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

Comando curl de exemplo:

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

Rastreamento de envio

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

  • Preferencial:use o Biblioteca JavaScript Shipment Tracking. A biblioteca mostra a localização de veículos e locais de interesse rastreado pelo Fleet Engine. Contém um componente de mapa JavaScript. que é uma substituição simples para um objeto google.maps.Map padrão, e os componentes de dados para conexão com o Fleet Engine. Esse componente permite que você fornecem uma experiência personalizável e animada de rastreamento de remessas do seu aplicativo da Web ou para dispositivos móveis.

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

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

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

Logging

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

Papéis e tokens de autorização

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

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

Solução de problemas comuns

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

Resiliência

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

Estado perdido no Fleet Engine

Ao trabalhar com o Fleet Engine, implemente os clientes para melhorar o sistema por conta própria em caso de falha. Por exemplo, quando o Fleet Engine tenta atualizar um veículo, ele poderá responder com um erro indicando que o veículo não está existem. O cliente precisa recriar o veículo no novo estado. Embora esse problema raramente ocorre, verifique se o sistema é resiliente o suficiente para lidar reimplantá-lo.

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

Perda de estado no app do motorista

Se o app do motorista falhar, o app vai precisar recriar o estado atual. no SDK do Driver. O app deve tentar recriar tarefas para garantir que eles existem e restaurar os estados atuais. O app também precisa recriar e definir explicitamente a lista de paradas do SDK do Driver.

Perguntas frequentes

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

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