Elige la información que quieras devolver
Cuando llamas a un método para procesar una ruta o una matriz de rutas, debes especificar la información que quieres y debes enumerar los campos 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
fields
, o con el encabezado HTTP o gRPC X-Goog-FieldMask
.
Usar una máscara de campo es una buena práctica de diseño para asegurarse de no solicitar datos innecesarios, lo que a su vez ayuda a evitar tiempos de procesamiento y cargos facturados innecesarios.
Para obtener más información acerca de 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 de acceso separadas por comas, en las que cada path especifica un campo único en el mensaje de respuesta. La ruta de acceso comienza en el mensaje de respuesta de nivel superior y usa un una ruta separada por puntos al campo especificado.
Crea y especifica una ruta de campo de la siguiente manera:
- Busca los campos que contienen la información que necesitas de la API de Routes. Para obtener más detalles, consulta Referencias de campo.
- 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.
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 el
distanceMeters
del segmento de la ruta, más la duración de cada paso de cada etapa de la ruta, ingresa ambos, separados por comas y sin espacios:routes.legs.distanceMeters,routes.legs.steps.duration
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
yX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Referencias de campo
Para ver los campos que puedes solicitar en una respuesta mediante 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
.
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
- Calcula máscaras de campo de matriz de ruta
- REST: Especifica los campos del Cuerpo de la respuesta para regresar.
- gRPC: especifica los campos del RouteMatrixElement en la respuesta que se devuelva.
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:
- Solicita todos los campos con una máscara de campo de
*
. - Observa la jerarquía de los campos en la respuesta del campos que desees.
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][...]
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 tramo de la ruta, haz lo siguiente: es decir, el último distanceMeters
del ejemplo anterior, tu máscara de campo es 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 es 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, se usa una llamada REST a la
computeRoutes
para calcular
por 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
Para el computeRouteMatrix
de REST
método utilizado para procesar una matriz de rutas, en el encabezado, especifica que se devuelva
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 requieres en la respuesta para que devuelva solo el campos 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 seleccionar todos los campos o, si seleccionas todos los campos en el nivel superior, puedes experimenta una degradación del rendimiento cuando se agregan campos nuevos y, luego, se incluirá 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.
Para obtener más detalles sobre la construcción de una máscara de campo, consulta la 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:
- Configura los siguientes parámetros obligatorios para mostrar un token de ruta:
- Establece
travelMode
enDRIVE
. - Establece
routingPreference
enTRAFFIC_AWARE
oTRAFFIC_AWARE_OPTIMAL
.
- Establece
- Verifica que ninguno de los puntos de referencia de tu ruta sea
via
. - Especifica la máscara de campo
routes.routeToken
para mostrar un token de ruta:X-Goog-FieldMask: routes.routeToken
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 Planificar una ruta (iOS).
Ejemplo de token de ruta
Este es un ejemplo de un cuerpo de solicitud cURL para un origen único, un destino único usando máscaras de campo para solicitar un token de ruta, junto con el nombre duración, distancia y polilínea de 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.