Elige la información que quieres devolver

Cuando llamas a un método para calcular una ruta o calcular una matriz de ruta, debes especificar qué información deseas; para ello, debes especificar qué campos quieres que se muestren 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, pasa la máscara de campo de respuesta a cualquiera de los métodos mediante el parámetro de URL $fields o fields, o bien con el encabezado HTTP o de gRPC X-Goog-FieldMask.

El enmascaramiento de campo es una práctica de diseño recomendada para garantizar que no solicites datos innecesarios, lo que 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 de campo de respuesta es una lista de rutas de acceso separadas por comas, en la que cada ruta especifica un campo único en el mensaje de respuesta. La ruta comienza desde el mensaje de respuesta de nivel superior y usa una ruta de acceso separada por puntos hacia el campo especificado.

Construye una ruta de campo de la siguiente manera:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Calcular máscara de campo de ruta
    • REST: Especifica los campos del objeto Route en la respuesta que se muestra, con el prefijo routes., por ejemplo, routes.distanceMeters.
    • gRPC: Especifica los campos del objeto Route en la respuesta que se mostrará.
  • Calcula máscaras de campo de la matriz de ruta

Para obtener más información sobre cómo construir máscaras de campo, consulta field_mask.proto.

Cómo determinar qué máscaras de campo usar

A continuación, te mostramos cómo determinar qué máscaras de campo deseas usar:

  1. Solicita todos los campos con una máscara de campo de *.
  2. Observa la jerarquía de los campos en la respuesta y determina qué campos quieres.
  3. Compila tu máscara de campo con la jerarquía de campos.

Por ejemplo, para esta respuesta parcial de una ruta de transporte público:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Si deseas mostrar solo el campo distanceMeters, tu máscara de campo será la siguiente:

routes.legs.distanceMeters

Otro ejemplo: Para que se muestre todo lo que se encuentra en legs en la respuesta, tu máscara de campo es la siguiente:

routes.legs

Especifica la ruta de acceso de un campo

En esta sección, se incluyen ejemplos sobre cómo especificar una ruta de campo como parte de una máscara de campo de respuesta.

Llamada REST a computeRoutes

En el primer ejemplo, se usa 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 Route.distanceMeters y Route.duration en la respuesta. Recuerda usar el prefijo routes en el nombre del campo.

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

Llamada 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 mostrará originIndex, destinationIndex y duration para cada combinación de origen y destino:

-H 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 la ruta del campo

Incluye solo los campos que necesitas en la respuesta. Mostrar solo los campos que necesitas:

  • Disminuye los tiempos de procesamiento, por lo que tus resultados se muestran con una latencia más baja.
  • Garantiza un rendimiento de latencia estable si la API agrega más campos de respuesta en el futuro y si esos campos nuevos requieren tiempo de procesamiento adicional. Si seleccionas todos los campos, o si seleccionas todos los campos de nivel superior, es posible que experimentes una degradación del rendimiento cuando todos los campos nuevos se incluyan de forma automática en tu respuesta.
  • Genera un tamaño de respuesta más pequeño, lo que se traduce en una mayor capacidad de procesamiento de la red.
  • Se asegura de no solicitar datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos facturados innecesarios.

Solicita un token de ruta

A fin de solicitar que la API de Routes muestre tokens de ruta para las rutas generadas, sigue los requisitos de devolución de un token de ruta y, luego, usa la máscara de campo routes.route_token a fin de solicitar el token:

  1. Establece travel_mode en DRIVING.
  2. Establece routing_preference en TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
  3. Comprueba que ninguno de los puntos de referencia de la ruta sea via.
  4. Especifica la máscara de campo del token de ruta:
    -H X-Goog-FieldMask: routes.route_token

Puedes usar tu ruta planificada en el SDK de Navigation. Si deseas obtener más información, consulta Cómo planificar una ruta (Android) o Cómo planificar una ruta (iOS).

Ejemplo de token de ruta

A continuación, se incluye un ejemplo de cuerpo de solicitud cURL para una ruta de un solo origen y destino, que usa 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.route_token,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.