JMESPath: Consultas avanzadas en la salida JSON de azd

¿Qué es JMESPath y por qué importa en `azd`?

JMESPath es un lenguaje de consulta para datos JSON. Permite seleccionar campos, filtrar colecciones y proyectar estructuras nuevas a partir de un documento JSON.

Desde azd 1.23.4, Azure Developer CLI permite aplicar expresiones JMESPath sobre la salida JSON mediante la opción --query, siempre que se use junto con -o json y el comando ejecutado devuelva JSON.

Esto resulta útil cuando trabajas con automatización, scripts de CI/CD o inspección rápida de configuración, porque puedes extraer solo la parte del resultado que necesitas sin tener que procesar manualmente toda la salida.

Un ejemplo típico es consultar una sección concreta de la configuración de azd:

azd config show -o json --query "template.sources"

La idea no es sustituir todos los usos de herramientas especializadas como jq, sino facilitar consultas directas en escenarios habituales de Azure Developer CLI.

Requisitos y uso básico

Para usar --query con azd, necesitas:

azd versión 1.23.4 o posterior.
Un comando que soporte salida JSON.
Ejecutar el comando con -o json.
Añadir la expresión JMESPath con --query.

Puedes comprobar la versión instalada con:

azd version

El patrón general es:

azd <comando> -o json --query "<expresion-jmespath>"

Por ejemplo:

azd config show -o json --query "template.sources"

Importante: --query no convierte cualquier comando en JSON. Solo se puede aplicar sobre comandos que ya generen salida JSON mediante -o json.

Ejemplo: consultar una sección de la configuración

El comando azd config show puede devolver la configuración en JSON. Si solo quieres inspeccionar las fuentes de plantillas configuradas, puedes consultar la ruta template.sources:

azd config show -o json --query "template.sources"

La salida tendrá únicamente esa subsección del documento JSON. Un resultado puede tener una forma similar a esta:

{
  "awesome-azd": {
    "key": "awesome-azd",
    "location": "https://aka.ms/awesome-azd/templates.json",
    "name": "Awesome AZD"
  }
}

Esta consulta evita revisar todo el documento de configuración cuando solo necesitas una rama concreta.

Proyecciones: devolver solo los campos necesarios

JMESPath permite transformar la salida para devolver objetos con los campos que te interesan.

Si template.sources contiene varias entradas, puedes proyectar únicamente el nombre y la ubicación de cada fuente:

azd config show -o json --query "template.sources.*.{name:name, location:location}"

La expresión anterior hace lo siguiente:

template.sources: accede a la sección de fuentes de plantillas.
*: proyecta los valores del objeto.
{name:name, location:location}: construye un objeto nuevo con los campos indicados.

Un resultado posible sería:

[
  {
    "name": "Awesome AZD",
    "location": "https://aka.ms/awesome-azd/templates.json"
  }
]

Este tipo de proyección es especialmente útil cuando vas a consumir la salida desde un script y quieres mantener un contrato simple.

Filtros: seleccionar elementos concretos

También puedes aplicar filtros sobre colecciones. Por ejemplo, si quieres localizar una fuente de plantillas por nombre:

azd config show -o json --query "template.sources.*[?name=='Awesome AZD']"

JMESPath usa la sintaxis [?condicion] para filtrar arrays. En este caso, la condición es:

name == 'Awesome AZD'

Si necesitas devolver únicamente la ubicación de las entradas coincidentes, puedes combinar filtro y proyección:

azd config show -o json --query "template.sources.*[?name=='Awesome AZD'].location"

La salida sería una lista con los valores de location que cumplan el filtro:

[
  "https://aka.ms/awesome-azd/templates.json"
]

Consultas sobre errores en JSON

El soporte de JMESPath en azd también aplica a salidas JSON de error cuando el comando las devuelve en ese formato.

La recomendación práctica es no asumir una estructura universal para todos los errores. Antes de crear una consulta estable, inspecciona la salida completa:

azd <comando> -o json

Una vez conocida la estructura real, puedes aplicar --query para extraer los campos relevantes.

Por ejemplo, si la salida JSON de un error incluyera un objeto error con campos como code y message, la consulta tendría una forma similar a:

azd <comando> -o json --query "error.{code:code, message:message}"

El punto importante es que la expresión debe ajustarse a la estructura exacta que devuelve el comando en tu versión de azd.

Buenas prácticas al usar `--query`

Empieza consultando el JSON completo

Antes de escribir una expresión compleja, ejecuta el comando sin --query:

azd config show -o json

Así puedes confirmar nombres de propiedades, niveles de anidamiento y si una sección es un objeto o un array.

Usa comillas correctamente según tu shell

En Bash, Zsh o PowerShell suele ser práctico envolver la expresión JMESPath entre comillas dobles:

azd config show -o json --query "template.sources"

Si la expresión contiene literales de texto, usa comillas simples dentro de la expresión:

azd config show -o json --query "template.sources.*[?name=='Awesome AZD']"

Evita depender de campos no documentados

Las consultas JMESPath dependen de la estructura JSON devuelta por el comando. Si automatizas procesos críticos, valida tus scripts al actualizar azd, especialmente si consultas campos muy específicos.

Mantén las consultas legibles

JMESPath permite construir expresiones potentes, pero en automatización conviene equilibrar concisión y mantenibilidad. Si una consulta resulta difícil de leer, quizá sea mejor dividir el flujo en pasos o documentarla en el script.

Diferencias con herramientas como `jq`

JMESPath integrado en azd cubre muchos escenarios habituales:

Extraer una propiedad concreta.
Filtrar arrays.
Proyectar objetos con un subconjunto de campos.
Reducir ruido en la salida de comandos.
Preparar datos para scripts sencillos.

Herramientas como jq siguen siendo útiles cuando necesitas transformaciones más avanzadas, procesamiento complejo o combinar varias fuentes JSON. La ventaja de --query en azd es la comodidad: puedes resolver consultas frecuentes sin añadir otra herramienta al flujo.

Limitaciones a tener en cuenta

Aunque la integración es útil, hay varios límites prácticos:

Solo funciona con salida JSON: debes usar -o json y el comando debe soportar ese formato.
No todos los comandos devuelven JSON: si un comando no genera JSON, --query no será aplicable.
La consulta depende de la estructura del resultado: cambios en el JSON pueden afectar scripts existentes.
No reemplaza validaciones de negocio: una consulta JMESPath filtra datos, pero no sustituye controles explícitos en automatizaciones críticas.

Conclusión

El soporte de JMESPath en azd simplifica la forma de trabajar con la salida JSON de Azure Developer CLI. Con -o json --query, puedes extraer secciones concretas, filtrar colecciones y proyectar resultados más limpios directamente desde la terminal.

Para equipos que usan azd en scripts, pipelines o tareas de inspección diaria, esta funcionalidad reduce pasos intermedios y hace más cómodos los flujos de automatización. La clave es usarla con criterio: comprobar primero la estructura JSON real, mantener consultas legibles y validar los scripts cuando actualices la CLI.

Más información en el anuncio oficial: JMESPath support comes to azd JSON output.

¿Qué es JMESPath y por qué importa en azd?