Esta página foi traduzida pela API Cloud Translation.

Faça sua primeira solicitação de otimização de rotas

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

Este documento mostra 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 o ambiente de produção, a recomendação geral é usar o gRPC devido aos benefícios de performance. 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 que funciona das 7h às 19h em São Francisco. Hoje de manhã, você precisa buscar dois cachorros em locais diferentes da cidade. Os dois tutores de cachorro deram uma janela de coleta entre 7h30 e 9h30.

Você tem uma van para o trabalho e paga ao motorista US$ 27 por hora. O motorista e a van começam o dia na creche às 7h e precisam voltar das coletas da manhã até as 12h para um intervalo para o almoço.

Hoje é 13 de fevereiro de 2024, e o motorista tem as seguintes tarefas:

Pegue o Boiadeiro de Berna perto da Coit Tower.
Pegue o chihuahua no South Sunset Playground Park.
Deixe os dois cachorros na creche para cães no Mission Dolores Park.

Você precisa de um trajeto que minimize o tempo que os cachorros passam na van e atenda aos requisitos de embarque e desembarque.

Antes de começar

Para executar o código neste exemplo, primeiro siga 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 seu problema de otimização.

Como esse cenário de creche para cachorros é uma solicitação pequena e direta, use um método de bloqueio, como optimizeTours, que entrega resultados rapidamente para solicitações pequenas. Para mais informações sobre os métodos da API Route Optimization, consulte Endpoints síncronos e assíncronos.

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

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

Além disso, defina tempos limite e prazos curtos para reduzir qualquer tempo de espera desnecessário. Para esse cenário de creche para cachorros, o otimizador não precisa de muito tempo para responder à sua solicitação. Use as seguintes configurações:

Defina o parâmetro timeout como 2 segundos.
Mantenha as configurações de prazo 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 é construir o corpo da mensagem de solicitação.

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

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

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).
Defina os envios. No campo shipments, adicione uma mensagem Shipment para cada cachorro que precisa ser buscado e deixado pela manhã. É aqui que você define o local e os horários de embarque preferidos do dono do cachorro e o local e os horários de desembarque da creche.
1. Para cada cachorro, crie um VisitRequest para retiradas e outro para as entregas, que, para este cenário, são chamadas de deixar na creche.
  - Em retiradas, defina o arrivalWaypoint como o local de retirada do cachorro (Torre Coit para o boiadeiro bernês ou Parque South Sunset Playground para o chihuahua) e o timeWindows como o horário de retirada solicitado pelo proprietário (7h30 às 9h30).
  - Em entregas, defina o arrivalWaypoint como a creche e o timeWindows para o horário de entrega necessário (das 9h30 às 11h30).
  Para mais informações sobre períodos, consulte Períodos.
2. Use o campo label para adicionar um identificador a cada envio, como "Bernese mountain dog" e "Chihuahua". Isso pode ajudar você a identificar os envios na resposta.
Para mais informações sobre como definir remessas, consulte Remessa.
Defina os veículos. No campo vehicles, adicione uma mensagem Vehicle para uma van com a creche como ponto de partida e de chegada, o custo do salário do motorista e as horas de operação 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, defina 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.
  
  Importante: os custos são essenciais para que o otimizador encontre o melhor trajeto. Sem eles, o otimizador trata todas as soluções como iguais.
3. Para garantir que o otimizador crie um trajeto dentro do horário de funcionamento da van, defina startTimeWindows como o intervalo aceitável para o motorista começar a operar o veículo e endTimeWindows como o intervalo aceitável para o retorno à creche. Para mais informações sobre períodos, consulte Períodos.
Defina um período global. A janela de tempo global representa o período em que a van pode fazer coletas e entregas para sua creche ao longo do dia. Para esse cenário, defina globalStartTime como 7h e globalEndTime como 19h de 13 de fevereiro de 2024, que representam o horário de funcionamento da creche para cachorros.

3. Enviar a solicitação

Confira a seguir uma solicitação curl simples baseada no cenário de creche para cachorros e 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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
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 parentesco ou por pesquisa de texto.

Com filhos	Parâmetro	Tipo de propriedade	Descrição
`OptimizeToursRequest`	`model`	object (`ShipmentModel`)	Essa é a essência da sua solicitação. É um único objeto em que você define todo o problema, incluindo todos os cachorros que precisam ser pegos e deixados (`shipments`) e a van na sua frota (`vehicles`). Pense nisso como o projeto completo do problema que você precisa otimizar.
`OptimizeToursRequest`	`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 diminuir o tempo de espera. Para solicitações pequenas e rápidas, como este cenário de creche para cachorros, defina esse valor como 2 segundos.
`ShipmentModel`	`shipments[]`	matriz de objetos (`Shipment`)	É uma matriz de objetos em que cada objeto representa um cachorro que precisa ser buscado ou deixado.
	`vehicles[]`	matriz de objetos (`Vehicle`)	É uma matriz de objetos em que cada objeto define um veículo na sua frota. É onde você descreve seus recursos, como a van que faz as retiradas e entregas. Você precisa definir pelo menos um veículo para receber uma rota otimizada.
	`globalStartTime`	Carimbo de data/hora	É o momento mais cedo possível para qualquer evento em todo o modelo. Esse parâmetro reduz o problema de otimização ao longo do tempo, o que é crucial para cálculos precisos de tráfego e rotas. Para esse cenário de creche para cachorros, defina esse campo como o horário mais cedo em que o motorista pode dirigir a van no dia, que é 7h em 13 de fevereiro de 2024.
	`globalEndTime`	Carimbo de data/hora	Esse é o horário mais recente possível para qualquer evento em todo o modelo. Para esse cenário de creche para cachorros, defina esse valor como o horário em que a van deve encerrar a operação, que é 19h do dia 13 de fevereiro de 2024.
`Shipment`	`pickups[]`	matriz de objetos (`VisitRequest`)	Esta é uma lista de todas as opções de retirada possíveis para o envio. O otimizador escolhe a melhor opção para resolver seu problema. Para esse cenário de creche para cachorros, liste os locais e horários de retirada que cada proprietário forneceu para cada cachorro.
	`deliveries[]`	matriz de objetos (`VisitRequest`)	Esta é uma lista de todas as opções de entrega possíveis para o envio. O otimizador escolhe a melhor opção para resolver seu problema. Para esse cenário de creche para cachorros, liste o local da creche e o período em que o motorista precisa voltar para o almoço de cada cachorro.
	`label`	string	É um identificador de um envio específico na sua solicitação. Você pode especificar rótulos na solicitação para facilitar a leitura da resposta. Para esse cenário de creche para cachorros, 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.
`VisitRequest`	`arrivalWaypoint[]`	object (`Waypoint`)	É o local de uma visita específica no trajeto. É possível definir isso usando coordenadas de latitude e longitude, um ID de lugar ou um título. Neste cenário de creche para cachorros, defina isso como o local fornecido pelo proprietário para `pickups` e como o endereço da creche para `deliveries`.
`VisitRequest`	`timeWindows[]`	matriz de objetos (`TimeWindow`)	É uma matriz de objetos que definem as restrições de tempo para uma coleta ou entrega. Para esse cenário, use isso para definir o período de retirada de cada um dos cachorros e o período aceitável para deixá-los na creche.
`Vehicle`	`startWaypoint[]`	object (`Waypoint`)	É o local de início 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 começar o trajeto. Se você não definir esse waypoint, o otimizador vai escolher uma das retiradas ou entregas como local de partida. Para esse cenário de creche para cachorros, como o motorista começa o dia na creche, use as coordenadas do Mission Dolores Park.
	`endWaypoint[]`	object (`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. Para esse cenário de creche para cachorros, como o motorista precisa terminar o dia na creche, use as coordenadas do Mission Dolores Park.
	`costPerHour`	número	É o custo incorrido por cada hora de uso de um veículo, independente de estar em movimento ou parado. Para esse cenário de creche para cachorros, use isso para modelar o salário por hora de um motorista.
	`startTimeWindows[]`	matriz de objetos (`TimeWindow`)	Essa é a janela aceitável para o motorista começar a dirigir a van para as coletas de cachorros da manhã.
	`endTimeWindows[]`	matriz de objetos (`TimeWindow`)	Esse é o período aceitável para o motorista terminar de dirigir a van e estacionar de volta no centro de creche para cachorros.

Interpretar a resposta