Realiza tu primera solicitud de optimización de rutas

Desarrolladores del Espacio Económico Europeo (EEE)

En este documento, se muestra cómo realizar tu primera solicitud a la API de Route Optimization con una situación de uso real.

Para simplificar, en el ejemplo, se usan HTTP y JSON para demostrar la API de REST. Sin embargo, para tu entorno de producción, se recomienda usar gRPC por sus beneficios de rendimiento. Sin embargo, gRPC requiere cierta instalación. Para obtener más información, consulta Bibliotecas cliente de la API de Route Optimization.

Situación

Mapa de San Francisco con pines para la Coit Tower, el Mission Dolores Park y el South Sunset Playground Park

Administras un servicio de guardería para perros de 7:00 a.m. a 7:00 p.m. en San Francisco. Esta mañana, debes recoger dos perros de diferentes ubicaciones de la ciudad. Ambos dueños de perros te dieron un período de recogida entre las 7:30 a.m. y las 9:30 a.m.

Tienes una camioneta para el trabajo y le pagas al conductor 27 dólares por hora. El conductor y la camioneta comienzan el día en tu guardería a las 7:00 a.m. y deben regresar de las recogidas de la mañana a las 12:00 p.m. para un descanso para almorzar.

Hoy es 13 de febrero de 2024, y el conductor tiene las siguientes tareas:

Recoger al boyero de Berna cerca de la Torre Coit
Recoger al chihuahua en el parque South Sunset Playground
Dejar a ambos perros en la guardería en Mission Dolores Park

Necesitas una ruta que minimice el tiempo que los perros pasan en la camioneta y que cumpla con los requisitos de recogida y entrega.

Antes de comenzar

Para ejecutar el código en esta situación de ejemplo, primero debes completar las instrucciones en Configura la API de Route Optimization.

1. Elige tu enfoque de optimización de rutas

La API de Route Optimization tiene varios métodos para que elijas según la complejidad de tu problema de optimización.

Dado que esta situación de guardería para perros es una solicitud pequeña y directa, usa un método de bloqueo, como optimizeTours, que entrega resultados rápidamente para solicitudes pequeñas. Para obtener más información sobre los métodos de la API de Route Optimization, consulta Extremos síncronos y asíncronos.

Usa la siguiente URL para realizar una solicitud HTTP POST al optimizeTours método:

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

También debes configurar los parámetros de configuración de tiempo de espera y fecha límite para que sean breves y reducir cualquier tiempo de espera innecesario. Para esta situación de guardería para perros, el optimizador no necesita mucho tiempo para responder a tu solicitud, por lo que debes usar la siguiente configuración:

Establece el timeout parámetro en 2 segundos.
Deja la configuración de fecha límite en el valor predeterminado, que es de 60 segundos para las solicitudes de REST.

2. Crea el cuerpo del mensaje de solicitud

Después de elegir el método de bloqueo optimizeTours y definir la configuración de tiempo de espera y fecha límite, el siguiente paso es crear el cuerpo del mensaje de solicitud.

En esta situación, la solicitud es un mensaje OptimizeToursRequest codificado como JSON en la API de REST.

Para crear el mensaje de solicitud, sigue los siguientes pasos:

Comienza con la estructura de solicitud básica, que es la siguiente:
```
{
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}
```
Para obtener más información sobre la estructura, consulta la guía de conceptos clave para la estructura base (ShipmentModel, Shipment y Vehicle).
Define los envíos. En el campo shipments, agrega un mensaje Shipment para cada perro que deba recogerse y entregarse por la mañana. Aquí es donde defines la ubicación y los horarios de recogida preferidos de cada dueño de perro, y la ubicación y los horarios de la guardería para dejar a los perros.
1. Para cada perro, crea un VisitRequest para las recogidas y otro para las entregas, que, en esta situación, se conoce como la entrega de la guardería.
  - En las recogidas, establece arrivalWaypoint en la ubicación de recogida del perro (Torre Coit para el boyero de Berna o el parque South Sunset Playground para el chihuahua) y el timeWindows en el horario de recogida solicitado por el dueño (de 7:30 a.m. a 9:30 a.m.).
  - En las entregas, establece arrivalWaypoint en la guardería y timeWindows para el horario de entrega requerido (de 9:30 a.m. a 11:30 a.m.).
  Para obtener más información sobre los períodos, consulta Períodos.
2. Puedes usar el campo label para agregar un identificador para cada envío, como "boyero de Berna" y "chihuahua". Esto puede ayudarte a identificar los envíos en la respuesta.
Para obtener más información sobre la definición de envíos, consulta Envío.
Define los vehículos. En el campo vehicles, agrega un mensaje Vehicle para tu camioneta con la guardería como los puntos de inicio y finalización, el costo del salario del conductor y las horas operativas de la camioneta.
1. Establece startWaypoint y endWaypoint para la camioneta en las ubicaciones de inicio y finalización del día, que es la guardería cerca de Mission Dolores Park.
2. Para minimizar los costos de operación, debes definir las restricciones de costos de tu empresa. Establece el parámetro de costo costPerHour en 27, que es lo que le pagas al conductor por conducir la camioneta de la guardería para perros. Para obtener más información sobre los parámetros de costo, consulta Modelo de costos.
  
  Importante: Los costos son esenciales para que el optimizador encuentre la mejor ruta. Sin ellos, el optimizador trata todas las soluciones como iguales.
3. Para asegurarte de que el optimizador cree una ruta dentro de las horas operativas de la camioneta, define startTimeWindows en el rango aceptable para que el conductor comience a operar la camioneta y endTimeWindows en el rango aceptable para cuando el conductor debe regresar a la guardería. Para obtener más información sobre los períodos, consulta Períodos.
Para obtener más información sobre la definición de vehículos, consulta Vehículo.
Establece un período global. El período global representa el período durante el cual la camioneta puede realizar recogidas y entregas para tu guardería durante todo el día. Para esta situación, establece globalStartTime en las 7:00 a.m. y globalEndTime en las 7:00 p.m. del 13 de febrero de 2024, que representan las horas operativas de tu guardería para perros.

3. Envía la solicitud

La siguiente es una solicitud curl simple basada en la situación de la guardería para perros y usa el método de bloqueo optimizeTours.

Antes de enviar la solicitud, reemplaza PROJECT_NUMBER_OR_ID en el código de muestra por el ID de tu proyecto de 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
                }
              }
            },
            "timeWindows": [
              {
                "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
                }
              }
            },
            "timeWindows": [
              {
                "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 solicitud usados en la solicitud

En la siguiente tabla, se describen los parámetros de solicitud que se usan en el cuerpo de la solicitud de la situación de ejemplo. Puedes filtrar el contenido por elemento superior o por búsqueda de texto.

Padres	Parámetro	Tipo de propiedad	Descripción
`OptimizeToursRequest`	`model`	objeto (`ShipmentModel`)	Este es el núcleo de tu solicitud. Es un objeto único en el que defines todo tu problema, incluidos todos los perros que debes recoger y dejar (`shipments`) y la camioneta de tu flota (`vehicles`). Piensa en él como el plano completo del problema que debes optimizar.
`OptimizeToursRequest`	`timeout`	Duración	Este parámetro especifica el tiempo máximo que el servidor trabaja en una solicitud antes de mostrar una respuesta. Usa este parámetro para acortar el tiempo de espera. Para solicitudes pequeñas y rápidas, como esta situación de guardería para perros, establece este valor en 2s.
`ShipmentModel`	`shipments[]`	arreglo de objetos (`Shipment`)	Es un arreglo de objetos en el que cada objeto representa un perro que debe recogerse o dejarse.
	`vehicles[]`	arreglo de objetos (`Vehicle`)	Es un arreglo de objetos en el que cada objeto define un vehículo en tu flota. Aquí es donde describes tus recursos, como la camioneta que realiza las recogidas y las entregas. Debes definir al menos un vehículo para obtener una ruta optimizada.
	`globalStartTime`	Marca de tiempo	Esta es la hora más temprana posible para que ocurra cualquier evento en todo tu modelo. Este parámetro reduce el problema de optimización en el tiempo, lo que es fundamental para obtener cálculos precisos de tráfico y rutas. Para esta situación de guardería para perros, establece este parámetro en la hora más temprana en que el conductor puede operar la camioneta durante el día, que es a las 7:00 a.m. del 13 de febrero de 2024.
	`globalEndTime`	Marca de tiempo	Esta es la hora más tardía posible para que ocurra cualquier evento en todo tu modelo. Para esta situación de guardería para perros, establece este parámetro en el momento en que la camioneta finalice su operación, que es a las 7:00 p.m. del 13 de febrero de 2024.
`Shipment`	`pickups[]`	arreglo de objetos (`VisitRequest`)	Esta es una lista de todas las opciones de recogida posibles para el envío. El optimizador elige la mejor para resolver tu problema. Para esta situación de guardería para perros, enumera las ubicaciones de recogida y los períodos que cada dueño proporcionó para cada perro.
	`deliveries[]`	arreglo de objetos (`VisitRequest`)	Esta es una lista de todas las opciones de entrega posibles para el envío. El optimizador elige la mejor para resolver tu problema. Para esta situación de guardería para perros, enumera la ubicación de la guardería para perros y el período en el que el conductor debe regresar para almorzar para cada perro.
	`label`	string	Este es un identificador para un envío específico en tu solicitud. Puedes especificar etiquetas en tu solicitud para que sea más fácil leer la respuesta. Para esta situación de guardería para perros, usa una cadena descriptiva como "chihuahua", "boyero de Berna" o el nombre del perro para hacer coincidir la solución con tu entrada cuando recibas la respuesta de la API.
`VisitRequest`	`arrivalWaypoint[]`	objeto (`Waypoint`)	Esta es la ubicación de una visita específica en la ruta. Puedes definirla con coordenadas de latitud y longitud, un ID de lugar o un rumbo. En esta situación de guardería para perros, establece este parámetro en la ubicación proporcionada por el dueño para `pickups` y en la dirección de la guardería para `deliveries`.
`VisitRequest`	`timeWindows[]`	arreglo de objetos (`TimeWindow`)	Es un arreglo de objetos que definen las restricciones de tiempo para una recogida o entrega. Para esta situación, úsalo para definir el período de recogida de cada uno de los perros y el período aceptable para dejarlos en la guardería.
`Vehicle`	`startWaypoint[]`	objeto (`Waypoint`)	Esta es la ubicación de inicio de la ruta del vehículo, definida con coordenadas de latitud y longitud o un ID de lugar. Este parámetro le indica al optimizador dónde debe comenzar la ruta del vehículo. Si no defines este punto de referencia, el optimizador elige una de las recogidas o entregas como la ubicación de inicio. Para esta situación de guardería para perros, como el conductor comienza el día en la guardería, usa las coordenadas de Mission Dolores Park.
	`endWaypoint[]`	objeto (`Waypoint`)	Este es el destino final de la ruta del vehículo, definido con coordenadas de latitud y longitud o un ID de lugar. Este parámetro le indica al optimizador dónde debe finalizar la ruta del vehículo. Si no defines este punto de referencia, el optimizador elige una de las recogidas o entregas como el final de la ruta. Para esta situación de guardería para perros, como el conductor debe finalizar el día en la guardería, usa las coordenadas de Mission Dolores Park.
	`costPerHour`	número	Este es el costo en el que se incurre por cada hora que se usa un vehículo, independientemente de si está en movimiento o detenido. Para esta situación de guardería para perros, use esto para modelar el salario por hora de un conductor.
	`startTimeWindows[]`	arreglo de objetos (`TimeWindow`)	Este es el período aceptable para que el conductor comience a conducir la camioneta para las recogidas de perros por la mañana.
	`endTimeWindows[]`	arreglo de objetos (`TimeWindow`)	Este es el período aceptable para que el conductor termine de conducir la camioneta y la estacione de nuevo en la guardería para perros.

Interpreta la respuesta