Definición de una consulta de elementos de trabajo en Azure Boards

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

Visual Studio 2019 | Visual Studio 2022

Las consultas de elementos de trabajo generan listas de elementos de trabajo en función de los criterios de filtro que se especifiquen. Puede guardar y compartir estas consultas administradas con otros usuarios.

Cree consultas desde el portal web o desde un cliente compatible, como Team Explorer de Visual Studio. Para admitir actualizaciones o adiciones masivas, importe o exporte consultas mediante archivos de Excel o archivos .csv.

Cree consultas desde el portal web o desde un cliente compatible, como Team Explorer de Visual Studio. Para admitir actualizaciones o adiciones masivas, importe o exporte consultas mediante Excel.

Consulte nuestros procedimientos recomendados, que encontrará en este mismo artículo.

Requisitos previos

  • Debe tener acceso de parte interesada para ver y ejecutar consultas compartidas. De forma predeterminada todos los miembros del proyecto tienen acceso de parte interesada. Para más información, consulte Cambiar los permisos de una consulta o carpeta compartidas.
  • Para agregar y guardar una consulta compartida, es preciso tener acceso Básico o superior.
  • Debe tener el permiso Contribuir establecido en Permitir para la carpeta a la que desea agregar la consulta. De forma predeterminada, el grupo Colaboradoresno tiene este permiso.

Nota:

Los usuarios con acceso de parte interesada para un proyecto público tienen acceso total a las características de consultas, al igual que los usuarios con acceso Básico. Para obtener más información, consulte Referencia rápida sobre el acceso de parte interesada.

  • De manera predeterminada, todos los miembros del proyecto y los usuarios con acceso de parte interesada pueden ver y ejecutar todas las consultas compartidas. Puede cambiar los permisos establecidos para una carpeta de consultas compartidas o una consulta compartida. Para más información, consulte Configuración de permisos de consulta.
  • Para agregar y guardar una consulta en Consultas compartidas, debe tener acceso Básico o superior. Además, debe tener establecido el permiso Contribuir en Permitir para la carpeta a la que desea agregar la consulta. De manera predeterminada, el grupo Colaboradores no tiene este permiso.

Elección de un filtro de consulta

En el Editor de Power Query, puede seleccionar el filtro para ir a un artículo con consultas de ejemplo. Junto con los filtros de consulta, puede aplicar filtros de forma interactiva a los resultados de la consulta.

Nota:

Las consultas administradas no admiten búsquedas por proximidad, pero sí las admiten las búsquedas semánticas. Además, las búsquedas semánticas admiten * y ? como caracteres comodín y puede usar más de un carácter comodín para que coincida con más de un carácter. Para más información, consulte Búsqueda de elementos de trabajo funcionales.


Características de filtro

Macros



También puede filtrar interactivamente una consulta mediante la función Filter.

Abrir consultas

En el explorador web, (1) compruebe que ha seleccionado el proyecto correcto, (2) elija Paneles>Consultas y, después, (3) elija Todo.

Open Boards>Queries, vertical nav

Si es la primera vez que abre Consultas, la página se abre en Favoritos. En esta página, se enumeran las consultas que ha indicado como favoritas. De lo contrario, puede elegir Todo para ver todas las consultas definidas y compartidas definidas para el proyecto.

Sugerencia

Las consultas que usted o su equipo han elegido como favoritos aparecen en la página Favoritos. Junto con otros objetos, las consultas favoritas también aparecen en la página Proyecto. Para más información, consulte Establecer favoritos personales o de equipo.

En el explorador web, abra Paneles > Consultas.

From your web browser, open Boards>Queries

Definición de una consulta de lista plana

Inicie una consulta nueva desde la pestaña Consultas del portal web o la pestaña Elementos de trabajo de Team Explorer.

Seleccione Nueva consulta.

Screenshot to Add new query, new experience.

El editor de consultas se muestra con la siguiente configuración predeterminada: Lista plana de elementos de trabajo, Tipo de elemento de trabajo=[Any] y Estado=[Any].

Screenshot of Query Editor with flat list of work items selected.

Modifique los valores y agregue o quite cláusulas, o bien cambie el valor de Tipo de consulta a Elementos de trabajo y vínculos directos o a Árbol de elementos de trabajo.

Screenshot to Queries page, Choose New query from the drop down menu.

El editor de consultas se muestra con la siguiente configuración predeterminada: Lista plana de elementos de trabajo, Proyecto de equipo=@Project (el proyecto actual), Tipo de elemento de trabajo=[Any] y Estado=[Any].

Screenshot of Query Editor with flat list of work items selected.

Puede modificar los valores y agregar o quitar cláusulas. O bien, cambie el campo Tipo de consulta a Elementos de trabajo y vínculos directos o a Árbol de elementos de trabajo.

Consulta entre proyectos o dentro de ellos

De forma predeterminada, el ámbito de las nuevas consultas se establece en el proyecto actual. Sin embargo, puede crear consultas para buscar elementos de trabajo definidos dentro de la organización o la colección de proyectos. Sin embargo, todas las consultas se guardan en un proyecto concreto.

Para enumerar los elementos de trabajo definidos en dos o más proyectos, active la casilla Consultar en los proyectos. Por ejemplo, la consulta siguiente busca todas las características creadas en todos los proyectos en los últimos 30 días.

Screenshot of Query Editor with Query across projects checked.

Con la opción Consultar en los proyectos activada, puede agregar el campo Proyecto de equipo para filtrar a un número seleccionado de proyectos.

Screenshot of Query Editor with Team Project and other fields added to filter.

Nota:

Separe los distintos nombres de proyecto con el separador de lista que corresponde a la configuración regional definida en el equipo cliente, por ejemplo, una coma ,.

  • El campo Proyecto de equipo solo está disponible después de activar Consultar en los proyectos.
  • Cuando la opción Consultar en los proyectos está activada, aparecen en el menú desplegable Campo todos los campos de todos los tipos de elementos de trabajo definidos en todos los proyectos de la colección.
  • Si la opción Consultar en los proyectos está desactivada, en el menú desplegable Campo solo aparecen los campos de esos tipos de elemento de trabajo, tal como se ha definido en el proyecto actual.

Definición de una cláusula

Para crear una consulta, defina una o varias cláusulas. Cada cláusula define un criterio de filtro para un único campo.

Cláusula de consulta de ejemplo

Y/O Campo Operador Value
Y Asignado a = @Me

Para obtener una lista de operadores disponibles en función del tipo de datos del campo, consulte Uso de un índice para consultar datos de referencia rápida en Azure Boards y Azure DevOps.

Todas las cláusulas se agregan como una instrucción And. Seleccione Or para cambiar la agrupación. Agrupe las cláusulas para asegurarse de que las instrucciones de la cláusula se ejecuten en la secuencia necesaria.

Seleccione Agregar nueva cláusula para agregar otra cláusula al final de la consulta y, después, elija el campo, el operador y el valor de esa cláusula.

Screenshot of Query Editor showing how to add a clause.

Por ejemplo, busque todos los elementos de trabajo que se le han asignado; para ello, especifique el campo Asignado a, el operador igual a (=) y la macro @Me, que representa su identidad de usuario.

Sugerencia

Para ver la sintaxis WIQL de una consulta y cómo se usan los paréntesis para agrupar cláusulas, instale el Editor de WIQL de Marketplace. Esta extensión admite la visualización de la sintaxis WIQL y la exportación a un archivo WIQL para su uso en las llamadas a las API REST. Para más información, consulte Sintaxis del lenguaje de consultas de elemento de trabajo (WIQL).

Lista de comprobación para definir una cláusula de consulta

  1. En la primera fila vacía, bajo el encabezado de la columna Campo, elija la flecha hacia abajo para mostrar la lista de campos disponibles y elija un elemento en la lista. Para obtener más información, consulte Campos y valores de consulta.

  2. En la misma fila, bajo el encabezado de columna Operador, seleccione la flecha hacia abajo para mostrar la lista de operadores disponibles y, después, elija un elemento en la lista. Para obtener más información, vea Operadores (Guía de programación de C#).

  3. En la misma fila, bajo el encabezado de la columna Valor, escriba un valor o seleccione la flecha hacia abajo y, después, elija un elemento en la lista. Para obtener más información sobre cómo usar una macro o una variable para especificar el proyecto actual, el usuario, la fecha u otra selección, consulte Variables.

  4. Para agregar una cláusula, seleccione Agregar nueva cláusula.

    Puede agregar una cláusula al final de la consulta o realizar las siguientes tareas con los iconos correspondientes:

    • Insertar nueva línea de filtro
    • Quitar esta línea de filtro
    • Agrupar cláusulas seleccionadas
    • Desagrupar cláusulas

Uso de un árbol de elementos de trabajo para ver las jerarquías

Use la consulta Árbol de elementos de trabajo para ver una lista anidada de varios niveles de elementos de trabajo. Por ejemplo, puede ver todos los elementos de trabajo pendiente y sus tareas vinculadas. Para centrarse en diferentes partes del árbol, seleccione Expandir todo o Contraer todo.

Nota:

No se puede construir una consulta que muestre una vista jerárquica de planes de pruebas, conjuntos de pruebas y casos de prueba. Estos elementos no están vinculados entre sí mediante tipos de vínculo primario/secundario. Sin embargo, puede crear una consulta de vínculos directos que muestre los elementos de trabajo relacionados con pruebas. Además, puede ver la jerarquía desde la página Test Plans.

Screenshot of Query Results List showing a Tree Query.

Screenshot of Query Results List showing a Tree Query.

Defina los criterios de filtro para los elementos de trabajo primarios y secundarios. Para buscar los elementos secundarios vinculados, seleccione Buscar primero elementos de trabajo de nivel superior. Para buscar los elementos primarios vinculados, seleccione Buscar primero elementos de trabajo vinculados.

Screenshot of Query Editor view of Tree of work items.

Utilice la consulta Elementos de trabajo y vínculos directos para hacer un seguimiento de los elementos de trabajo que dependen de otros trabajos de los que se hace seguimiento, como tareas, errores, problemas o características. Por ejemplo, puede ver los elementos de trabajo pendiente que dependen de otros elementos que se están implementando o de un error que se está corrigiendo.

Use la consulta de vínculos directos para realizar un seguimiento de las dependencias entre equipos. La consulta también le ayuda a administrar los compromisos que toma el equipo. Seleccione los criterios de filtro para los elementos de trabajo principales y vinculados. Y seleccione los tipos de vínculos para filtrar las dependencias.

Screenshot of Direct Links Query Results.

Screenshot of Query Editor, Direct Links Query.

Filtre la lista de primer nivel de elementos de trabajo eligiendo una de estas opciones:

  • Devolver solo elementos que tienen vínculos coincidentes: se devuelven los elementos de trabajo de primer nivel, pero solo si tienen vínculos a elementos de trabajo especificados por los criterios de filtro de elementos de trabajo vinculados.
  • Devolver todos los elementos de nivel superior: se devuelven todos los elementos de trabajo de primer nivel sin tener en cuenta los criterios de filtro de elementos de trabajo vinculados. Se devuelven los elementos de trabajo de segundo nivel vinculados al primer nivel si coinciden con los criterios de filtro de elementos de trabajo vinculados.
  • Devolver solo elementos de trabajo que no tienen vínculos coincidentes: se devuelven los elementos de trabajo de primer nivel, pero solo si no tienen vínculos a los elementos de trabajo especificados por los criterios de filtro de elementos de trabajo vinculados.

Para más información sobre cada tipo de vínculo, vea Referencia de tipo de vínculo.

Uso de la expresión lógica And/Or

Especifique And u Or para crear las expresiones lógicas de las cláusulas de consulta. Use And para buscar los elementos de trabajo que cumplen los criterios tanto de la cláusula actual como de la anterior. Use Or para buscar los elementos de trabajo que cumplen el criterio ya sea de la cláusula actual o de la anterior.

Agregue una nueva cláusula para cada campo del elemento de trabajo para refinar los criterios de búsqueda. Agregue cláusulas para devolver solo el conjunto de elementos de trabajo que desee. Si no recibe los resultados esperados de la consulta, refine la consulta. Puede agregar, quitar, agrupar o desagrupar cláusulas de consulta para mejorar los resultados de la consulta.

Agrupe cláusulas de consulta para trabajar como una sola unidad independiente del resto de la consulta. Agrupar cláusulas es similar a colocar paréntesis alrededor de una expresión en una ecuación matemática o una instrucción lógica. Cuando se agrupan cláusulas, los operadores And u Or de la primera cláusula del grupo se aplican a todo el grupo.

Agrupar cláusulas

Las cláusulas agrupadas funcionan como una sola unidad independiente del resto de la consulta. Agrupar cláusulas es similar a colocar paréntesis alrededor de una ecuación matemática o una expresión lógica. El operador And u Or de la primera cláusula del grupo se aplica a todo el grupo.

Tal y como se muestra en los ejemplos siguientes, las cláusulas agrupadas se traducen a la expresión lógica correspondiente.

Consultar Cláusulas agrupadas Expresión lógica
1 Screenshot showing a group clause query. Filters are set up for the Work item type field and either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type, State, and Assigned to fields. An OR operator groups the State and Assigned to fields.
2 Screenshot showing a group clause query, with filters for both the Work item type field and one of either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type with the State or Assigned to fields, which are grouped by an OR operator.
3 Screenshot showing a group clause query. Filters are set up for either the Work item type field or both the State field and the Assigned to field. Screenshot of a logical expression. An OR operator links the Work item type to both the State and the Assigned to fields, which are linked by an AND operator.

Estas consultas devuelven elementos de trabajo que son de tipo Error y cumplen las siguientes expresiones lógicas:

  • Consulta 1: AND State=Active OR Assigned to @Me
  • Consulta 2: AND (State=Active OR Assigned to @Me)
  • Consulta 3: OR (State=Active AND Assigned to @Me)

Para agrupar una o varias cláusulas, selecciónelas y seleccione el icono de agrupar cláusulas .

Screenshot of Web portal, Query Editor, Group Selected Query Clauses.

También puede agrupar varias cláusulas agrupadas. Active las casillas de cada cláusula. A continuación, elija el icono de agrupar cláusulas .

Screenshot of Web portal, Query Editor, Group multiple query clauses.

Si los resultados de la consulta no devuelven los resultados esperados, siga estos pasos:

  • Asegúrese de que las cláusulas están definidas como deseaba.
  • Compruebe las asignaciones de And/Or para cada cláusula. Si los resultados contienen más elementos de trabajo de lo esperado, a menudo se debe a que hay una cláusula Or, en lugar de una cláusula And.
  • Determine si necesita agrupar o cambiar la agrupación de las cláusulas de consulta y las asignaciones And/Or de cada cláusula agrupada.
  • Agregue más cláusulas de consulta para afinar los criterios de filtro para su consulta.
  • Revise las opciones disponibles para especificar campos, operadores y valores.
  • Consulte los procedimientos recomendados, que encontrará en este artículo.

Desagrupar una cláusula

Para desagrupar una cláusula, seleccione el icono de desagrupar cláusulas correspondiente a la cláusula agrupada.


Visualización de los resultados de la consulta en un panel

Los dos widgets siguientes muestran los resultados de la consulta. Puede abrir elementos de trabajo directamente desde estos widgets.

  • Trabajo asignado a mí: enumera todos los elementos de trabajo propuestos o activos asignados al usuario que ha iniciado sesión. Enumera los campos Identificador, Estado y Título.
  • Widget de resultados de la consulta: muestra los resultados de una consulta plana, de árbol o de vínculos directos. Puede configurar los campos que se muestran mediante el widget, cambiar el tamaño de los campos de columna y expandir y contraer el árbol y la consulta de vínculos directos.

Para más información, consulte Adición de widgets a un panel.

Visualización del widget de resultados de la consulta con títulos primarios

Puede ver los resultados de una consulta que muestre el título Primario. Para ello, realice estos pasos:

  1. Cree la consulta que filtra los elementos de trabajo de interés. La consulta puede ser una consulta de lista plana, de árbol o de vínculos directos.
  2. Agregue el campo Primario como una columna.
  3. Guarde la consulta como consulta compartida o favorito del equipo.
  4. Agregue el widget de resultados de la consulta al panel y configure la consulta. Asegúrese de que el campo Primario esté establecido para mostrarse.

En la imagen siguiente, se muestra un widget de resultados de la consulta que muestra el campo Primario.

Screenshot of query results widget showing a Parent column field.

Un hipervínculo de consulta usa el lenguaje de consultas de elemento de trabajo (WIQL), similar a Transact-SQL. Para más información, consulte Sintaxis del lenguaje de consultas de elemento de trabajo (WIQL).

Nota:

La mayoría de los exploradores aplican un límite de entre 2000 y 2083 caracteres para una cadena de dirección URL.

Codifique la parte de código WIQL de la sintaxis de la dirección URL. Puede usar cualquier herramienta de codificador de direcciones URL para codificar la dirección URL.

https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

Por ejemplo, el siguiente hipervínculo muestra el identificador y el título de todos los errores activos definidos en la ruta de acceso del área FabrikamFiber/Web para la organización Fabrikam.

https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'

El código WIQL descodificado se ajusta a:

SELECT [System.ID], [System.Title]
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug'
   AND [System.State]='Active'
   AND [System.AreaPath]='FabrikamFiber\Web'

Nota:

La longitud de WIQL no debe superar los 32 000 caracteres de las consultas de Azure Boards.

https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

Por ejemplo, el siguiente hipervínculo muestra el identificador, el título y el estado de todos los errores en la ruta de acceso del área FabrikamFiber/Web.

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20

Por ejemplo, consulte la siguiente entrada sin codificar.

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=
SELECT [System.ID], [System.Title], [System.State] 
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug' 
   AND [System.AreaPath]='FabrikamFiber\Web'   

procedimientos recomendados

Los siguientes procedimientos recomendados se aplican a las siguientes consultas que puede crear:

Creación de consultas centradas y selectivas

Defina una consulta muy selectiva aplicando todos los filtros necesarios para la consulta. Cuanto más selectiva sea la consulta, menor será el conjunto de resultados. Cuanto menor sea el conjunto de resultados, más dirigida y selectiva será la consulta.

Uso de etiquetas para clasificar elementos de trabajo

Use etiquetas de elemento de trabajo para clasificar los elementos de trabajo en lugar de un campo personalizado. Las consultas que filtran por etiquetas suelen tener más rendimiento que las consultas que filtran por coincidencias de cadena.

A diferencia de las coincidencias de campos personalizados o las coincidencias parciales, una consulta con una operación Tags Contains no requiere un recorrido completo de todas las tablas de elementos de trabajo.

Uso de Contains words para coincidencias de cadena

Para filtrar por una coincidencia de cadena, use Contains Words en lugar del operador Contains. El operador Contains Words ejecuta una búsqueda de texto completo en el campo especificado, que tiende a finalizar más rápidamente.

El operador Contains ejecuta un recorrido de tabla, que es una operación más lenta que la del operador Contains Words. También consume más ciclos de CPU. Estos ciclos de CPU pueden provocar que encuentre limitaciones de velocidad. Para obtener más información, consulte Limitación de frecuencia y uso.

Especificar grupos pequeños con el operador In Group

El operador In Group filtra los elementos de trabajo en función de coincidencias dentro de un grupo de valores. El grupo de valores corresponde a los contenidos en un equipo, grupo de seguridad o categoría de seguimiento de trabajo. Por ejemplo, puede crear una consulta para buscar todos los elementos de trabajo asignados a cualquier miembro de un equipo. O bien, buscar todos los elementos de trabajo que pertenecen a la categoría de requisitos (Microsoft.RequirementCategory).

Al filtrar por un grupo que contenga un gran número de miembros, el conjunto de resultados tiende a ser mayor y no selectivo. Además, si un grupo corresponde a un grupo grande de Microsoft Entra, la consulta genera un costo bastante grande para resolver ese grupo desde Microsoft Entra ID.

Evitar el uso de operadores de negación

Los operadores de negación, como <>, Not In, Not Under, Not In Group, tienden a generar consultas no selectivas y conjuntos de resultados grandes.

Los operadores de negación solo deben usarse cuando sea absolutamente necesario. Intente siempre encontrar alternativas primero. Por ejemplo, si Field1 tiene los valores A, B, C y D, especifique la cláusula Field1 In A, B, C, en lugar de la cláusula de negación Field1 <> D.

Evitar comparaciones de cadenas

Las consultas que contienen comparaciones de cadenas generan recorridos de tabla que son intrínsecamente ineficaces. En su lugar, se recomienda usar etiquetas o un campo personalizado específico como alternativas, especialmente cuando una consulta tiene un rendimiento deficiente.

Limitar los operadores Or

Limite el número de operadores Or definidos en la consulta. Las consultas se ejecutan mejor cuando se usan menos operadores Or. El uso de demasiados operadores Or puede hacer que la consulta no sea selectiva. Si la consulta se ejecuta lentamente, vuelva a ordenar la cláusula del operador Or hacia la parte superior de las cláusulas de consulta.

Guardar la consulta

Debido a optimizaciones internas, las consultas guardadas tienden a tener mejor rendimiento que las consultas no guardadas. Guarde siempre la consulta cuando planee reutilizarla. Incluso en el caso de las consultas WIQL que se ejecutan mediante una API REST, guarde el código WIQL mediante el portal web para que las llamadas a la API REST, ya que serán menos propensas a regresiones de rendimiento futuras.

Ejecución de la consulta

A veces, es necesario ejecutar la consulta varias veces para acceder al plan de optimización adecuado. Asegúrese de guardar la consulta y ejecutarla hasta 10 veces en un período de 30 minutos. De esta forma, el sistema puede examinar y buscar el plan de optimización más adecuado para la consulta.