Faça sua primeira solicitação de otimização de rota… com cachorros

Desenvolvedores do Espaço Econômico Europeu (EEE)

Neste documento, mostramos como fazer sua primeira solicitação à API Route Optimization usando um cenário de caso de uso real.

Para simplificar, o exemplo usa HTTP e JSON para demonstrar a API REST. No entanto, para seu ambiente de produção, a recomendação geral é usar o gRPC devido aos benefícios de desempenho. No entanto, o gRPC requer alguma instalação. Para mais informações, consulte Bibliotecas de cliente da API Route Optimization.

Cenário

Um mapa de São Francisco com alfinetes para a Coit Tower, o Mission Dolores Park e o South Sunset Playground Park

Você tem uma creche para cachorros em São Paulo que funciona das 7h às 19h. Esta manhã, você quer buscar três cachorros em locais diferentes da cidade e levá-los para a creche.

O boiadeiro de Berna e o chihuahua são clientes regulares que agendaram as consultas na semana passada. O pastor alemão é um pedido novo, de última hora. Você quer acomodar o pastor alemão, se possível, mas não às custas dos seus clientes regulares.

Você tem uma van para o trabalho e paga US $27 por hora ao motorista. O motorista e a van começam o dia na creche às 7h e precisam voltar das coletas matinais até o meio-dia para o almoço.

Hoje é 13 de fevereiro de 2024. Todos os horários neste cenário são o horário local de São Francisco, que é o horário padrão do Pacífico (UTC-8) em fevereiro. O driver tem as seguintes tarefas:

  • Pegue o boiadeiro de Berna perto da Coit Tower. O proprietário pediu uma janela de retirada curta, entre 8h e 8h20.
  • Pegue o chihuahua no South Sunset Playground Park. O proprietário ofereceu um período de retirada mais flexível, entre 7h30 e 9h30.
  • Pegue o pastor alemão em Land's End. O proprietário também pediu uma janela de coleta curta, entre 8h e 8h20.
  • Deixe os cachorros na creche do Mission Dolores Park. A creche exige que as crianças sejam deixadas entre 9h30 e 11h30.

Cada visita de retirada e entrega leva 5 minutos para carregar ou descarregar o cachorro.

Como Land's End fica longe da Coit Tower e as janelas de retirada entram em conflito, o motorista não pode realizar as três retiradas. O otimizador precisa escolher qual cachorro pular para minimizar o custo total (salários dos motoristas e penalidades por pular).

Antes de começar

Para executar o código neste cenário de exemplo, primeiro conclua as instruções em Configurar a API Route Optimization.

1. Escolher sua abordagem de otimização de rotas

A API Route Optimization tem vários métodos para você escolher, dependendo da complexidade do problema de otimização.

Como esse cenário de creche para cães é uma solicitação pequena e simples, use um método de bloqueio, como optimizeTours, que gera resultados rápidos para solicitações pequenas. Para mais informações sobre os endpoints da API Route Optimization, consulte Escolher um endpoint.

Use o URL a seguir para fazer uma solicitação POST HTTP para o método optimizeTours:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Também é necessário definir as configurações de tempo limite e prazo para que sejam curtas, reduzindo qualquer tempo de espera desnecessário. Para esse cenário de creche para cães, o otimizador não precisa de muito tempo para responder à solicitação. Portanto, use as seguintes configurações:

  • Defina o parâmetro timeout como 2 segundos.
  • Mantenha as configurações de prazo no padrão, que é de 60 segundos para solicitações REST.

2. Criar o corpo da mensagem de solicitação

Depois de escolher o método de bloqueio optimizeTours e definir as configurações de tempo limite e prazo, a próxima etapa é criar o corpo da mensagem de solicitação.

Neste cenário, a solicitação é uma mensagem OptimizeToursRequest codificada como JSON na API REST.

Para criar a mensagem de solicitação, siga estas etapas:

  1. Comece com a estrutura básica de solicitação, que é a seguinte:

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Para mais informações sobre a estrutura, consulte o guia de conceitos principais para Estrutura básica (ShipmentModel, Shipment e Vehicle).

  2. Defina as remessas. No campo shipments, adicione uma mensagem Shipment para cada cachorro que precisa ser buscado e deixado de manhã. É aqui que você define os locais e horários de retirada preferidos do tutor do cachorro, além dos locais e horários da creche para deixar os cachorros.

    1. Para cada cachorro, crie um VisitRequest para as coletas e outro para as entregas, que, neste cenário, são chamadas de entregas na creche.

      • Em retiradas, defina o arrivalWaypoint como o local de retirada do cachorro (Coit Tower para o Boiadeiro de Berna, South Sunset Playground Park para o Chihuahua ou Land's End para o Pastor Alemão). Defina o timeWindows como o horário de retirada solicitado pelo proprietário (das 8h às 8h20 para o boiadeiro de Berna e o pastor alemão, e das 7h30 às 9h30 para o chihuahua).

      • Nas entregas, defina o arrivalWaypoint como a creche e o timeWindows para o horário de entrega necessário (das 9h30 às 11h30).

      • Para todas as retiradas e entregas, defina o duration como 5 minutos (300s) para considerar o tempo de embarque e desembarque dos cachorros.

      Para mais informações sobre janelas de tempo, consulte Janelas de tempo.

    2. Para priorizar clientes regulares, defina o penaltyCost como 1000 para o boiadeiro de Berna e o chihuahua, e 100 para o pastor alemão. Com os custos de penalidade definidos, o otimizador pode pular qualquer um dos cachorros, mas considera pular o pastor alemão (que tem uma penalidade menor) primeiro se as restrições impossibilitarem a realização de todas as coletas.

    3. Use o campo label para adicionar um identificador para cada remessa, como "Bernese mountain dog", "Chihuahua" e "German shepherd". Isso pode ajudar a identificar as remessas na resposta.

    Para mais informações sobre como definir remessas, consulte Remessa.

  3. Defina os veículos. No campo vehicles, adicione uma mensagem Vehicle para sua van com a creche como ponto de partida e de chegada, o custo do salário do motorista e o horário de funcionamento da van.

    1. Defina startWaypoint e endWaypoint para a van nos locais de início e término do dia, que é a creche perto do Mission Dolores Park.

    2. Para minimizar os custos de operação, é preciso definir as restrições de custo da sua empresa. Defina o parâmetro de custo costPerHour como 27, que é o valor pago ao motorista para dirigir a van da creche para cachorros. Para mais informações sobre parâmetros de custo, consulte Modelo de custo.

    3. Para garantir que o otimizador crie um trajeto dentro do horário de funcionamento da van, defina uma janela de operação para o veículo. Essa janela define as restrições de horário de início e término do trajeto. Ao definir apenas uma metade de cada janela de tempo, você dá ao otimizador flexibilidade para iniciar o trajeto mais tarde ou encerrá-lo mais cedo:

      • Definir startTime em startTimeWindows como 7h significa que o motorista pode começar o turno às 7h. Ele também pode começar mais tarde se não houver retiradas de manhã cedo.

      • Definir endTime em endTimeWindows como meio-dia significa que o motorista precisa encerrar o turno até esse horário. Eles também podem encerrar o turno assim que concluírem a última entrega.

      Omitir a outra metade das janelas minimiza os tempos de espera e desvio do motorista. Para mais informações sobre janelas de tempo, consulte Janelas de tempo.

    Para mais informações sobre como definir veículos, consulte Veículo.

  4. Defina uma janela de tempo global. A janela de tempo global representa o período em que a van pode realizar coletas e entregas para a creche ao longo do dia. Para esse cenário, defina globalStartTime como 7h e globalEndTime como 19h para 13 de fevereiro de 2024, que representam o horário de funcionamento da creche para cães.

3. Enviar a solicitação

Veja a seguir uma solicitação curl simples baseada no cenário de creche para cachorros que usa o método de bloqueio optimizeTours.

Antes de enviar a solicitação, substitua PROJECT_NUMBER_OR_ID no exemplo de código pelo ID do projeto do Google Cloud.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": "2s",
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Bernese mountain dog",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00-08:00",
                "endTime": "2024-02-13T09:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Chihuahua",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.78018,
                  "longitude": -122.51194
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "German shepherd",
        "penaltyCost": 100
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00-08:00"
          }
        ],
        "endTimeWindows": [
          {
            "endTime": "2024-02-13T12:00:00-08:00"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00-08:00",
    "globalEndTime": "2024-02-13T19:00:00-08:00"
  }
}
EOM

Parâmetros de solicitação usados na solicitação

A tabela a seguir descreve os parâmetros de solicitação usados no corpo da solicitação do cenário de exemplo. É possível filtrar o conteúdo por pai ou por Text Search.

Com filhos Parâmetro Tipo de propriedade Descrição
OptimizeToursRequest model objeto (ShipmentModel) Esse é o núcleo da sua solicitação. É um único objeto em que você define todo o problema, incluindo todos os cães que precisa buscar e deixar (shipments) e a van da sua frota (vehicles). Pense nisso como o plano completo para o problema que você precisa otimizar.
timeout Duração Esse parâmetro especifica o tempo máximo que o servidor trabalha em uma solicitação antes de retornar uma resposta. Use esse parâmetro para reduzir o tempo de espera. Para solicitações pequenas e rápidas, como este cenário de creche para cães, defina esse valor como 2s.
ShipmentModel shipments[] matriz de objetos (Shipment) Essa é uma matriz de objetos em que cada objeto representa um cachorro que precisa ser buscado ou deixado.
vehicles[] matriz de objetos (Vehicle) Essa é uma matriz de objetos em que cada objeto define um veículo na sua frota. É onde você descreve seus recursos, como a van que realiza as coletas e entregas. É necessário definir pelo menos um veículo para receber uma rota otimizada.
globalStartTime Carimbo de data/hora Esse é o momento mais cedo possível para que qualquer evento ocorra em todo o modelo. Esse parâmetro restringe o problema de otimização no tempo, o que é crucial para cálculos precisos de tráfego e rotas. Para este cenário de creche para cães, defina o horário mais cedo em que o motorista pode operar a van no dia, que é 7h em 13 de fevereiro de 2024.
globalEndTime Carimbo de data/hora Esse é o horário mais tardio possível para que qualquer evento ocorra em todo o modelo. Para este cenário de creche para cães, defina o horário em que a van deve encerrar a operação, que é às 19h de 13 de fevereiro de 2024.
Shipment pickups[] matriz de objetos (VisitRequest) Esta é uma lista de todas as opções de retirada possíveis para a remessa. O otimizador escolhe a melhor para resolver seu problema. Para esse cenário de creche para cães, liste os locais de retirada e os períodos que cada proprietário forneceu para cada cão.
deliveries[] matriz de objetos (VisitRequest) Esta é uma lista de todas as opções de entrega possíveis para a remessa. O otimizador escolhe a melhor para resolver seu problema. Para esse cenário de creche para cães, liste o local da creche e o período em que o motorista precisa voltar para o almoço de cada cão.
label string É um identificador de uma remessa específica na sua solicitação. É possível especificar rótulos na solicitação para facilitar a leitura da resposta. Para esse cenário de creche para cães, use uma string descritiva como "Chihuahua", "Bernese mountain dog" ou o nome do cachorro para corresponder à solução à sua entrada quando você receber a resposta da API.
penaltyCost double Esse é o custo de penalidade incorrido se o otimizador pular essa remessa. Por padrão, as remessas são obrigatórias. O otimizador prioriza a minimização de remessas obrigatórias ignoradas e só as ignora quando não há outra opção. Definir um custo de penalidade permite que o otimizador pule uma remessa se ela for inviável ou muito cara para ser realizada, além de permitir que você pondere as prioridades entre as remessas. Nesse cenário, você define um custo de penalidade maior (1000) para seus clientes regulares (Bernese e Chihuahua) e um custo de penalidade menor (100) para o pedido de última hora do pastor alemão. Isso informa ao otimizador que ele deve priorizar os clientes regulares, então ele considera pular o pastor alemão primeiro quando não pode realizar todas as coletas.
VisitRequest arrivalWaypoint objeto (Waypoint) É o local de uma visita específica no trajeto. Você pode definir isso usando coordenadas de latitude e longitude, um ID de lugar ou uma direção. Neste cenário de creche para cães, defina o local fornecido pelo proprietário para pickups e o endereço da creche para deliveries.
timeWindows[] matriz de objetos (TimeWindow) É uma matriz de objetos que definem as restrições de tempo para uma retirada ou entrega. Nesse cenário, use isso para definir a janela de retirada de cada um dos cães e a janela aceitável para deixá-los na creche.
duration Duração Esse parâmetro especifica a duração da visita (por exemplo, tempo de carga ou descarga). Nesse cenário, você define um buffer de 5 minutos (300s) para todas as retiradas e entregas, considerando o tempo que o motorista leva para colocar e tirar os cachorros do veículo.
Vehicle startWaypoint objeto (Waypoint) É o local de partida do trajeto do veículo, definido com coordenadas de latitude e longitude ou um ID de lugar. Esse parâmetro informa ao otimizador onde o veículo precisa iniciar o trajeto. Se você não definir esse waypoint, o otimizador vai escolher uma das retiradas ou entregas como o local de partida. Nesse cenário de creche para cães, como o motorista começa o dia na creche, use as coordenadas do Mission Dolores Park.
endWaypoint objeto (Waypoint) É o destino final do trajeto do veículo, definido com coordenadas de latitude e longitude ou um ID de lugar. Esse parâmetro informa ao otimizador onde o veículo precisa terminar o trajeto. Se você não definir esse waypoint, o otimizador vai escolher uma das retiradas ou entregas como o fim do trajeto. Neste cenário de creche para cães, como o motorista precisa terminar o dia na creche, use as coordenadas do Mission Dolores Park.
costPerHour número É o custo incorrido para cada hora de uso de um veículo, independentemente de ele estar em movimento ou parado. Para este cenário de creche para cães, use isso para modelar o salário por hora de um motorista.
startTimeWindows[] matriz de objetos (TimeWindow) É o período aceitável para o motorista iniciar o turno. Para este cenário de creche para cães, defina startTime como 7h, mas omita endTime. Isso permite que o otimizador atrase o início do turno se a primeira retirada for mais tarde pela manhã. Mesmo que você não forneça um endTime para startTimeWindows, o horário de início será implicitamente limitado pelo endTimeWindows. O veículo precisa iniciar o trajeto antes que ele termine.
endTimeWindows[] matriz de objetos (TimeWindow) Esse é o período aceitável para o motorista concluir o trajeto. Para este cenário de creche para cães, defina endTime como meio-dia, mas omita startTime. Isso permite que o motorista volte à creche imediatamente após a última entrega.

Avançar

Interpretar a resposta