Elige la información que quieras devolver

Cuando llamas a un método para procesar una ruta o una matriz de rutas, debes especificar qué información deseas con una lista de los campos que se mostrarán en la respuesta. No hay una lista predeterminada de los campos que se muestran. Si omites esta lista, los métodos mostrarán un error.

Para especificar la lista de campos, crea una máscara de campo de respuesta. Luego, debes pasar la máscara de campo de respuesta a cualquiera de los métodos con el parámetro de URL $fields o fields, o con el encabezado HTTP o gRPC X-Goog-FieldMask.

El uso de una máscara de campo es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que, a su vez, ayuda a evitar tiempos de procesamiento y cargos facturados innecesarios.

Para obtener más información sobre los parámetros de URL, consulta Parámetros del sistema.

Define una máscara de campo de respuesta

La máscara del campo de respuesta es una lista de rutas separadas por comas, en la que cada ruta especifica un campo único en el mensaje de respuesta. La ruta comienza en el mensaje de respuesta de nivel superior y usa una ruta de acceso separada por puntos al campo especificado.

Crea y especifica una ruta de campo de la siguiente manera:

1. Busca los campos que contienen la información que necesitas de la API de Routes. Para obtener más detalles, consulta Referencias de campo.
2. Determina las rutas de acceso para los campos que necesitas y crea las máscaras de campo para ellos: Para obtener más información, consulta Determina qué máscara de campo deseas usar.

3. Combina las máscaras de campo para todos los campos que necesites y separa las máscaras de campo con comas. Por ejemplo, para solicitar la distanceMeters del segmento de la ruta más la duración de cada paso de la ruta, ingresa ambas, separadas por comas y sin espacios:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. Envía la máscara de campo con tu solicitud a la API. Por ejemplo, en una solicitud cURL, debes especificar la máscara de campo con -H y X-Goog-FieldMask:

   -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration

Para obtener ejemplos y más detalles, consulta las siguientes secciones.

Referencias de campo

Para ver los campos que puedes solicitar en una respuesta a través de máscaras de campo, consulta las referencias de la API de Routes vinculadas en la siguiente lista. Especifica los campos con mayúsculas mediales, como se muestra en la referencia. Por ejemplo, routePreference.

Por el contrario, debe ingresar los parámetros values como se muestra. Por ejemplo, para routingPreference, debes ingresar TRAFFIC_AWARE.

Estas referencias incluyen los campos que están disponibles. Sin embargo, debes consultar la jerarquía de los campos para determinar la ruta de acceso a la máscara de campo completa. Para obtener detalles sobre cómo obtener la jerarquía de los campos, consulta Determina qué máscara de campo deseas usar.

• Máscara de campo de ruta de procesamiento
  • REST: Especifica los campos del objeto Route en la respuesta que se mostrará, con el prefijo routes., por ejemplo, routes.distanceMeters.
  • gRPC: Especifica los campos del objeto Route en la respuesta que se mostrará.
• Calcular máscaras de campo de matriz de ruta
  • REST: Especifica los campos del cuerpo de la respuesta que se mostrarán.
  • gRPC: Especifica los campos del objeto RouteMatrixElement en la respuesta que se mostrará.

Determina qué máscaras de campo usar

A continuación, te mostramos cómo puedes determinar qué campos quieres usar y construir las máscaras de campo para ellos:

1. Solicita todos los campos con una máscara de campo de *.
   Precaución: Si bien puedes usar esta máscara de campo comodín durante el desarrollo para determinar los campos que necesitas, no la uses en producción. Solicitar todos los campos en producción genera costos más altos y tiempos de respuesta más largos. Es posible que el costo también aumente de forma inesperada a medida que se agreguen funciones más avanzadas, ya que esta máscara de campo las incluirá automáticamente. En su lugar, solicita solo los campos que necesitas para minimizar los costos y el tiempo de respuesta.
2. Observa la jerarquía de los campos en la respuesta de los campos que desees.

3. Construye tus máscaras de campo con la jerarquía de los campos mostrados en el paso anterior con el siguiente formato:

   topLevelField[.secondLevelField][.thirdLevelField][...]

   Nota: No uses espacios en ninguna parte de la lista de rutas de campo.

Por ejemplo, para esta respuesta parcial de una ruta, usa lo siguiente:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Si deseas mostrar solo el campo distanceMeters para el segmento de la ruta, es decir, el último distanceMeters del ejemplo anterior, tu máscara de campo será la siguiente:

routes.legs.distanceMeters

En cambio, si deseas mostrar el campo distanceMeters para cada paso del segmento de la ruta, es decir, el distanceMeters en steps en el ejemplo anterior, tu máscara de campo será la siguiente:

routes.legs.steps.distanceMeters

Si deseas mostrar ambos, con el resultado anterior, tu máscara de campo es la siguiente:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Ejemplo de rutas de acceso de máscara de campo

Esta sección contiene más ejemplos sobre cómo especificar una ruta de campo como parte de una máscara de campo de respuesta en llamadas de REST y gRPC.

Llamada de REST a computeRoutes

En el primer ejemplo, usas una llamada de REST al método computeRoutes para calcular una ruta. En este ejemplo, en el encabezado, especificas máscaras de campo para mostrar los campos distanceMeters y duration de la ruta en la respuesta. Recuerda colocar el prefijo routes en el nombre del campo.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

Llamada de REST a computeRouteMatrix

En el método computeRouteMatrix de REST que se usa para calcular una matriz de ruta, en el encabezado, especifica que se muestre originIndex, destinationIndex y duration para cada combinación de origen y destino:

X-Goog-FieldMask: originIndex,destinationIndex,duration

Llamada a gRPC

Para gRPC, configura una variable que contenga la máscara de campo de respuesta. Luego, puedes pasar esa variable a la solicitud.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Consideraciones de las rutas de campo

Incluye solo los campos que necesitas en la respuesta para mostrar solo los que necesitas:

• Reduce los tiempos de procesamiento, por lo que tus resultados se devuelven con una latencia más baja.
• Garantiza un rendimiento de latencia estable. Si seleccionas todos los campos, o si lo haces en el nivel superior, es posible que experimentes una degradación del rendimiento cuando se agreguen campos nuevos y, luego, se incluyan automáticamente en tu respuesta.
• Genera un tamaño de respuesta más pequeño, lo que se traduce en una mayor capacidad de procesamiento de red.
• Se asegura de no solicitar datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos facturados innecesarios.

Nota: Cuando se analiza un mensaje de respuesta y un campo en el mensaje de respuesta contiene su valor predeterminado, este se puede omitir de la respuesta, incluso si lo especificaste en la máscara del campo de respuesta. Para obtener más información, consulta la Guía de lenguaje (proto3). Por ejemplo, cuando calculas una matriz de ruta, el campo distanceMeters de la respuesta puede contener un valor de 0, su valor predeterminado. Como 0 es el valor predeterminado de distanceMeters, se omite de la respuesta.

Para obtener más detalles sobre la construcción de una máscara de campo, consulta el field_mask.proto.

Solicita un token de ruta

Para solicitar que la API de Routes devuelva tokens de ruta para las rutas generadas, sigue estos pasos:

1. Configura los siguientes parámetros obligatorios para mostrar un token de ruta:
   • Establece travelMode en DRIVE.
   • Establece routingPreference en TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
2. Verifica que ninguno de los puntos de referencia de tu ruta sea via.
3. Especifica la máscara de campo routes.routeToken para mostrar un token de ruta:

   X-Goog-FieldMask: routes.routeToken

Nota: Debido a condiciones dinámicas de las rutas, las rutas generadas con un token determinado pueden diferir de la ruta planificada. Para minimizar las diferencias, usa el token unos minutos después de su generación.

Puedes usar el token de ruta para la ruta planificada en el SDK de Navigation. Para obtener más detalles, consulta Planifica una ruta (Android) o Planifica una ruta (iOS).

Ejemplo de token de ruta

A continuación, se muestra un ejemplo de un cuerpo de solicitud cURL para una ruta de origen único y destino único, con máscaras de campo para solicitar un token de ruta, junto con la duración, la distancia y la polilínea de la ruta:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Para obtener más detalles, consulta la referencia de la API de Compute Routes.