Desarrolladores del Espacio Económico Europeo (EEE)

Elige los campos que se devolverán

Cuando solicitas una ruta o una matriz de rutas, debes usar una máscara de campo para especificar qué información debe devolver la respuesta. No hay una lista predeterminada de campos devueltos. Si no especificas una máscara de campo, los métodos devuelven un error.

Usar una máscara de campo también garantiza que no solicites datos innecesarios, lo que, a su vez, ayuda con la latencia de respuesta y evita que se devuelva información que tu sistema no necesita.

Especifica la lista de los campos que necesitas en una máscara de campo de respuesta. Luego, pasas 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.

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 separada por comas de rutas de acceso, en la que cada ruta de acceso especifica un campo único en el mensaje de respuesta. La ruta de acceso comienza desde 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 acceso de campo de la siguiente manera:

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

  3. Combina las máscaras de campo para todos los campos que necesites y sepáralas con comas. Por ejemplo, para solicitar el distanceMeters del tramo de la ruta, además de la duración de cada paso del tramo, ingresa ambos valores separados por una coma, 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, especificarías la máscara de campo con -H y X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Para ver ejemplos y obtener más detalles, consulta las siguientes secciones.

Referencias de campos

Para ver los campos que puedes solicitar en una respuesta a través de máscaras de campo, consulta las referencias de Compute Routes o Compute Route Matrix de la API de Routes que se vinculan en la siguiente lista. Especifica los campos en 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 completa de la máscara de campo. Para obtener detalles sobre cómo obtener la jerarquía de los campos, consulta Determina qué máscara de campo quieres usar.

  • Máscara de campo de Compute Routes
    • REST: Especifica los campos del objeto Route en la respuesta que se devolverá, con el prefijo routes., por ejemplo, routes.distanceMeters.
    • gRPC: Especifica los campos del objeto Route en la respuesta que se devolverá.
  • Máscaras de campo de Compute Route Matrix

Determina qué máscaras de campo usar

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

  1. Solicita todos los campos con una máscara de campo de *.
  2. Observa la jerarquía de los campos en la respuesta para los campos que deseas.

  3. Crea tus máscaras de campo con la jerarquía de los campos que se muestran en el paso anterior, con este formato:

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

Por ejemplo, para esta respuesta parcial de una ruta:

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

Si solo quieres que se devuelva el campo distanceMeters del tramo de la ruta, es decir, el último distanceMeters del ejemplo anterior, tu máscara de campo es la siguiente:

routes.legs.distanceMeters

Si, en cambio, quieres que se devuelva el campo distanceMeters para cada paso del tramo de la ruta, es decir, el distanceMeters que se encuentra debajo de steps en el ejemplo anterior, tu máscara de campo es la siguiente:

routes.legs.steps.distanceMeters

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

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

Ejemplos de rutas de máscara de campo

En esta sección, se incluyen más ejemplos de cómo especificar una ruta de acceso 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 devolver los campos distanceMeters y duration de la ruta en la respuesta. Recuerda agregar el prefijo routes al nombre del campo.

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

Llamada de REST a computeRouteMatrix

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

Llamada de gRPC a computeRoutes

Para el método computeRoutes de gRPC que se usa para calcular una ruta, establece una variable que contenga la máscara de campo de respuesta para que se devuelvan los campos de ruta distanceMeters, duration y de polilínea codificada en la respuesta. Luego, puedes pasar esa variable a la solicitud:

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

Llamada de gRPC a computeRouteMatrix

Para el método gRPC computeRouteMatrix que se usa para calcular una matriz de rutas, establece una variable que contenga la máscara de campo de respuesta para especificar que se devuelvan originIndex, destinationIndex y duration para cada combinación de origen y destino. Luego, puedes pasar esa variable a la solicitud:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Consideraciones sobre la ruta de acceso del campo

Incluye solo los campos que necesitas en la respuesta para que se devuelvan solo los campos que necesitas:

  • Disminuye los tiempos de procesamiento, por lo que los resultados se devuelven con una latencia más baja.
  • Garantiza un rendimiento de latencia estable. Si seleccionas todos los campos, o si seleccionas todos los campos 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.
  • Garantiza que no solicites datos innecesarios, lo que ayuda a evitar tiempos de procesamiento y cargos de facturación adicionales.

Para obtener más detalles sobre cómo construir una máscara de campo, consulta field_mask.proto.