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 caso 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, la recomendación general es 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

Un mapa de San Francisco con pines para la Torre Coit, el parque Mission Dolores y el parque South Sunset Playground

Diriges 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 recolección 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 recolecciones 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 el boyero de Berna cerca de la Torre Coit
  • Recoger el 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 recolección 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.

Debido a 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 POST HTTP al optimizeTours método:

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

También debes establecer la configuración de tiempo de espera y fecha límite para que sea breve 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:

  1. 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).

  2. 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 recolección 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 recolecciones y otro para las entregas, que, en esta situación, se conoce como la entrega de la guardería.

      • En las partidas, establece arrivalWaypoint en la ubicación de partida del perro (Torre Coit para el boyero de Berna o el parque South Sunset Playground para el chihuahua) y timeWindows en la hora de partida solicitada 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.

  3. 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 destino, el costo del salario del conductor y el horario de atención 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.

    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.

  4. Establece un período global. El período global representa el período durante el cual la camioneta puede realizar recolecciones y entregas para tu guardería durante todo el día. En 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 el horario de atención de tu guardería para perros.

3. Envía la solicitud

A continuación, se muestra 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) Esta es la parte central 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.
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[] array de objetos (Shipment) Es un array de objetos en el que cada objeto representa un perro que debe recogerse o dejarse.
vehicles[] array de objetos (Vehicle) Es un array de objetos en el que cada objeto define un vehículo de tu flota. Aquí es donde describes tus recursos, como la camioneta que realiza las recolecciones 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 valor 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 valor en el momento en que se espera que la camioneta finalice su operación, que es a las 7:00 p.m. del 13 de febrero de 2024.
Shipment pickups[] array de objetos (VisitRequest) Esta es una lista de todas las opciones de recolección 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 recolección y los períodos que cada dueño proporcionó para cada perro.
deliveries[] array 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 y el período en el que el conductor debe regresar para almorzar para cada perro.
label string 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) 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 encabezado. En esta situación de guardería para perros, establece este valor en la ubicación proporcionada por el dueño para pickups y en la dirección de la guardería para deliveries.
timeWindows[] array de objetos (TimeWindow) Es un array de objetos que definen las restricciones de tiempo para una recolección o entrega. En esta situación, úsalo para definir el período de recolección de cada uno de los perros y el período aceptable para dejarlos en la guardería.
Vehicle startWaypoint[] objeto (Waypoint) 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 recolecciones 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) 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 recolecciones 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 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[] array de objetos (TimeWindow) Es el período aceptable para que el conductor comience a conducir la camioneta para las recolecciones de perros por la mañana.
endTimeWindows[] array de objetos (TimeWindow) 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.

Siguiente

Interpreta la respuesta