Definir uma consulta de item de trabalho no Azure Boards
Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019 | TFS 2018
Visual Studio 2019 | Visual Studio 2022
As consultas de item de trabalho geram listas de itens de trabalho com base nos critérios de filtro fornecidos por você. Você pode salvar e compartilhar essas consultas gerenciadas com outras pessoas.
Você pode criar consultas a partir do portal da Web ou de um cliente com suporte, como o Visual Studio Team Explorer. Para dar suporte a atualizações ou adições em massa, importe ou exporte consultas usando o Excel ou arquivos .csv.
Você pode criar consultas a partir do portal da Web ou de um cliente com suporte, como o Visual Studio Team Explorer. Para dar suporte a atualizações ou adições em massa, importe ou exporte consultas usando o Excel.
Confira nossas melhores práticas, mais adiante neste artigo.
Pré-requisitos
- Você deve ter acesso ao Stakeholder para exibir e executar consultas compartilhadas. Todos os membros do projeto têm acesso ao Stakeholder por padrão. Para obter mais informações, confira Alterar as permissões para uma consulta ou pasta compartilhada.
- Você deve ter acesso Básico ou superior para adicionar e salvar uma consulta compartilhada.
- Você deve ter sua permissão de Contribuição definida como Permitir para a pasta à qual deseja adicionar uma consulta. Por padrão, o grupo Colaboradoresnão tem essa permissão.
Observação
Os usuários com acesso de Stakeholders para um projeto público têm acesso completo aos recursos de consultas, assim como os usuários com acesso Básico. Para mais informações, veja Referência rápida de acesso das partes interessadas.
- Por padrão, todos os membros do projeto e usuários com acesso ao Stakeholder podem exibir e executar todas as consultas compartilhadas. Você pode alterar as permissões definidas para uma pasta de consulta compartilhada ou uma consulta compartilhada. Para obter mais informações, confira Definir permissões de consulta.
- Para adicionar e salvar uma consulta em Consultas compartilhadas, você deve receber acesso Básico ou superior. Além disso, você deve ter a permissão Contribuir definida como Permitir para a pasta à qual deseja adicionar a consulta. Por padrão, o grupo Colaboradores não tem essa permissão definida.
Escolher um filtro de consulta
No Editor de Consultas, você pode selecionar o filtro para ir para um artigo com consultas de exemplo. Além dos filtros de consulta, você pode aplicar filtros interativamente aos resultados da consulta.
Observação
As consultas gerenciadas não dão suporte a pesquisas de proximidade. Entretanto, as pesquisas semânticas dão. Além disso, as pesquisas semânticas dão suporte a * e ? como caracteres curinga e você pode usar mais de um caractere curinga para corresponder a mais de um caractere. Para obter mais informações, confira Pesquisa de item de trabalho funcional.
Filtrar recursos
Macros
Você também pode filtrar interativamente uma consulta usando a função 
Filtro.
Abrir consultas
No navegador da Web, (1) verifique se você selecionou o projeto certo, (2) escolha Boards > Consultas e, em seguida, (3) escolha Tudo.
Se for sua primeira vez abrindo Consultas, a página será aberta em Favoritos. Esta página lista as consultas que você indicou como favoritas. Caso contrário, você pode escolher Todas para exibir todas as consultas que você definiu e consultas compartilhadas definidas para o projeto.
Dica
Consultas que você ou sua equipe escolheram como favoritas aparecem na página Favoritos. As consultas favoritas, juntamente com outros objetos, também aparecem na página Projeto. Para obter mais informações, confira Definir favoritos pessoais ou de equipe.
No navegador da Web, abra Boards > Consultas.
Definir uma consulta de lista simples
Inicie uma nova consulta na guia Consultas no portal da Web ou na guia Itens de trabalho no Team Explorer.
Selecione Nova consulta.
O Editor de Consultas é exibido com as seguintes configurações padrão: Lista simples de itens de trabalho, Tipo de Item de Trabalho=[Qualquer]e Estado=[Qualquer].
Modifique os Valores e adicione ou remova cláusulas, ou altere o Tipo de consulta para Itens de trabalho e links diretos ou para uma Árvore de itens de trabalho.
O Editor de Consultas é exibido com as seguintes configurações padrão: Lista simples de itens de trabalho, Projeto de equipe=@Project (o projeto atual), Tipo de Item de Trabalho=[Qualquer]e Estado=[Qualquer].
Você pode modificar os Valores e adicionar ou remover cláusulas. Ou alterar o Tipo de consulta para Itens de trabalho e links diretos ou para uma Árvore de itens de trabalho.
Consultar entre ou dentro de projetos
As novas consultas examinam o projeto em curso por padrão. Porém, você pode criar consultas para localizar itens de trabalho definidos na organização ou na coleção de projetos. Todas as consultas salvas, no entanto, são salvas em um projeto específico.
Para listar itens de trabalho definidos em dois ou mais projetos, marque a marca de seleção Consulta entre projetos. Por exemplo, a consulta a seguir localiza todos os recursos criados em todos os projetos nos últimos 30 dias.
Com Consulta entre projetos selecionado, você pode adicionar o campo Projeto de Equipe para filtrar um número específico de projetos.
Observação
Separe vários nomes de projeto com o separador de lista que corresponde às configurações regionais definidas para o computador cliente, por exemplo, uma vírgula ,.
- O campo Projeto de Equipe só estará disponível depois que você marcar Consulta entre projetos.
- Quando a Consulta entre projetos estiver marcada, todos os campos de todos os tipos de item de trabalho definidos em todos os projetos da coleção aparecem no menu suspenso Campo.
- Quando a Consulta entre projetos estiver desmarcada, somente os campos desses tipos de item de trabalho, conforme definido no projeto atual, aparecem no menu suspenso Campo.
Definir uma cláusula
Para criar uma consulta, defina uma ou mais cláusulas. Cada cláusula define um critério de filtro para um único campo.
Cláusula de consulta de amostra
| E/Ou | Campo | Operador | Valor |
|---|---|---|---|
| And | Atribuído a | = | @Me |
Para obter uma lista de operadores disponíveis com base no tipo de dados de campo, confira Referência rápida do índice de consulta.
Todas as cláusulas são adicionadas como uma instrução E. Selecione Ou para alterar o agrupamento. Cláusulas de grupo para garantir que as instruções de cláusula sejam executadas na sequência necessária.
Selecione Adicionar nova cláusula para adicionar outra cláusula no final da consulta e selecione o Campo, o Operador e o Valor dessa cláusula.
Por exemplo, pesquise todos os itens de trabalho atribuídos a você especificando o campo Atribuído a, o operador igual (=) e a macro @Me, que representa a identidade do usuário.
Excluir Cláusula.
Executar ou 
Salvar Consulta.Dica
Para exibir a sintaxe WIQL (Work Item Query Language) de uma consulta e como parênteses são usados para agrupar cláusulas, instale o Editor de Wiql do Marketplace. Essa extensão dá suporte à exibição da sintaxe WIQL e à exportação para um arquivo WIQL para uso em chamadas à API REST. Para obter mais informações, confira Sintaxe para a Work Item Query Language (WIQL).
Lista de verificação para definir uma cláusula de consulta
Na primeira linha vazia, no cabeçalho da coluna Campo, escolha a seta para baixo para exibir a lista de campos disponíveis e escolha um item na lista. Para obter mais informações, confira Campos e Valores de Consulta.
Na mesma linha, sob o título da coluna Operador, selecione a seta para baixo para exibir a lista de operadores disponíveis e escolha um item na lista. Para obter mais informações, consulte Operadores.
Na mesma linha, sob o título da coluna Valor, insira um valor ou selecione a seta para baixo e escolha um item na lista. Para obter mais informações sobre como usar uma macro ou variável para especificar o projeto atual, o usuário, a data ou outra seleção, confira Variáveis.
Para adicionar uma cláusula, escolha Adicionar nova cláusula.
Você pode adicionar uma cláusula ao final da consulta ou executar as seguintes tarefas com os ícones correspondentes:
Inserir nova linha de filtro
Remover esta linha de filtro
Agrupar cláusulas selecionadas
Desagrupar cláusulas
Usar uma árvore de itens de trabalho para exibir hierarquias
Use a consulta 
Árvore de Itens de trabalho para exibir uma lista aninhada de várias camadas de itens de trabalho. Por exemplo, você pode exibir todos os itens da lista de pendências e suas tarefas vinculadas. Para se concentrar em diferentes partes da árvore, escolha 
Expandir tudo ou 
Recolher tudo.
Observação
Você não pode construir uma consulta que mostre uma exibição hierárquica de Test Plans, Conjuntos de Testes e Casos de Teste. Esses itens não são vinculados usando tipos de link pai-filho. No entanto, você pode criar uma consulta de links diretos que lista itens de trabalho relacionados ao teste. Além disso, você pode exibir a hierarquia por meio da página Test Plans.
Defina os critérios de filtragem para os itens de trabalho pai e filho. Para localizar elementos filho vinculados, selecione Corresponder itens de trabalho de nível superior primeiro. Para localizar elementos pai vinculados, selecione Corresponder itens de trabalho vinculados primeiro.
Usar links diretos para exibir dependências
Use a consulta 
Itens de trabalho e links diretos para acompanhar itens de trabalho que dependem de outro trabalho rastreado, como tarefas, bugs, problemas ou recursos. Por exemplo, você pode exibir itens da lista de pendências que dependem de outros itens que estão sendo implementados ou um bug que está sendo corrigido.
Use a consulta de links diretos para rastrear dependências entre equipes. A consulta também ajuda você a gerenciar compromissos que sua equipe faz. Escolha os critérios de filtro para os itens de trabalho principais e vinculados. E selecione os tipos de links para filtrar as dependências.
Filtre a lista da primeira camada de itens de trabalho escolhendo uma destas opções:
- Retornar somente os itens de trabalho que não têm os vínculos correspondentes: os itens de trabalho da primeira camada são retornados, mas somente se estiverem vinculados a itens de trabalho especificados pelos critérios de filtragem de itens de trabalho vinculados.
- Retornar todos os itens de nível superior: todos os itens de trabalho de primeira camada retornam independente dos critérios de filtro de itens de trabalho vinculados. Os itens de trabalho da segunda camada que são vinculados à primeira camada são retornados quando correspondem aos critérios de filtragem de itens de trabalhos vinculados.
- Retornar somente os itens de trabalho que não têm os vínculos correspondentes: os itens de trabalho da primeira camada são retornados, mas somente se não estiverem vinculados a itens de trabalho especificados pelos critérios de filtragem de itens de trabalho vinculados.
Para obter mais informações sobre cada tipo de link, consulte Referência de tipo de link.
Usar expressão lógica e/ou
Especifique And ou Or para criar expressões lógicas de suas cláusulas de consulta. Use And para localizar itens de trabalho que atendam aos critérios na cláusula atual e na cláusula anterior. Use Or para localizar itens de trabalho que atendam ao critério na cláusula atual ou na cláusula anterior.
Adicione uma nova cláusula para cada campo de item de trabalho para refinar os critérios de pesquisa. Adicione cláusulas para retornar apenas o conjunto de itens de trabalho desejados. Se você não receber os resultados esperados da consulta, refina-os. Você pode adicionar, remover, agrupar ou desagrupar cláusulas de consulta para melhorar os resultados da consulta.
Agrupe as cláusulas de consulta para operarem como uma única unidade separada do restante da consulta. Agrupar cláusulas é como colocar uma expressão entre parênteses em uma equação matemática ou instrução lógica. Quando você agrupa cláusulas, And ou Or da primeira cláusula no grupo se aplica a todo o grupo.
Agrupar cláusulas
As cláusulas agrupadas operam como uma única unidade separada do restante da consulta. Agrupar cláusulas é como colocar parênteses em uma equação matemática ou instrução lógica. O operador And ou Or operador da primeira cláusula no grupo se aplica a todo o grupo.
Como mostrado nos exemplos a seguir, as cláusulas agrupadas são traduzidas para a expressão lógica correspondente.
| Query | Cláusulas agrupadas | Expressão lógica |
|---|---|---|
| 1 |  |
 |
| 2 |  |
 |
| 3 |  |
 |
Essas consultas retornam itens de trabalho que são do tipo Bug e atendem às seguintes expressões 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 uma ou mais cláusulas, selecione-as e selecione o ícone de cláusulas de grupo 
.
Você também pode agrupar várias cláusulas agrupadas. Marque as caixas de cada cláusula. Em seguida, escolha o ícone de cláusulas de grupo .
Se os resultados da consulta não retornarem os resultados esperados, execute as seguintes etapas:
- Verifique se cada cláusula está definida como você pretendia.
- Verifique as atribuições
And/Orpara cada cláusula. Se os resultados contiverem mais itens de trabalho do que o esperado, geralmente uma cláusulaOrestará presente em vez de uma cláusulaAnd. - Determine se você precisa agrupar ou alterar o agrupamento das cláusulas de consulta e as atribuições
And/Orde cada cláusula agrupada. - Adicione mais cláusulas de consulta para refinar seus critérios de filtragem de consulta.
- Examine as opções disponíveis para especificar campos, operadores e valores.
- Confira as práticas recomendadas, mais adiante neste artigo.
Desagrupar uma cláusula
Para desagrupar uma cláusula, selecione o ícone de desagrupar cláusulas 
para a cláusula agrupada.
Exibir resultados da consulta em um painel
Os dois widgets a seguir exibem os resultados da consulta. Você pode abrir itens de trabalho diretamente desses widgets.
- Trabalho atribuído a mim: lista todos os itens de trabalho propostos ou ativos atribuídos ao usuário conectado. Lista os campos ID, Estado e Título.
- Widget de resultados da consulta: exibe os resultados de uma consulta simples, de árvore ou de links diretos. Você pode configurar os campos exibidos por meio do widget, redimensionar os campos de coluna e expandir e recolher a consulta de árvore e links diretos.
Para obter mais informações, confira Adicionar widgets a um painel.
Exibir o widget de resultados da consulta com Títulos de elementos pai
Você pode exibir os resultados de uma consulta com o título Pai exibido. Para isso, realize estas etapas:
- Crie a consulta que filtra os itens de trabalho de interesse. A consulta pode ser uma consulta de lista simples, árvore ou links diretos.
- Adicione o campo Pai como uma coluna.
- Salve a consulta como uma Consulta compartilhada ou Favorito da equipe.
- Adicione o Widget resultados da consulta ao painel e configure a consulta. Verifique se o campo Pai está definido como exibido.
A imagem a seguir ilustra um widget de resultados de consulta que exibe o campo Pai.
Definir uma consulta como um hiperlink
O hiperlink de consulta usa a linguagem WIQL (Work Item Query Language), que lembra Transact-SQL. Para obter mais informações, confira Sintaxe para a Work Item Query Language (WIQL).
Observação
A maioria dos navegadores impõe um limite entre 2000 e 2083 caracteres para uma cadeia de caracteres de URL.
Sintaxe de hiperlink de consulta
Codificar a parte WIQL da sintaxe de URL. Você pode usar qualquer ferramenta de codificador de URL para codificar sua URL.
https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}
Por exemplo, o hiperlink a seguir lista a ID e o título de todos os bugs ativos definidos no caminho da área FabrikamFiber/Web para a organização 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'
O WIQL decodificado está em conformidade com:
SELECT [System.ID], [System.Title]
FROM WorkItems
WHERE [System.TeamProject]='FabrikamFiber'
AND [System.WorkItemType]='Bug'
AND [System.State]='Active'
AND [System.AreaPath]='FabrikamFiber\Web'
Observação
O comprimento do WIQL não deve exceder 32 mil caracteres para consultas do Azure Boards.
Sintaxe de hiperlink de consulta
https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}
Por exemplo, o hiperlink a seguir lista a ID, o título e o estado de todos os bugs no caminho da área da Web/FabrikamFiber.
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 exemplo, confira a seguinte entrada não codificada.
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'
Práticas recomendadas
As seguintes melhores práticas se aplicam às seguintes consultas que você pode criar:
Criar consultas seletivas e focadas
Defina uma consulta altamente seletiva aplicando todos os filtros necessários para sua consulta. Quanto mais seletiva for a consulta, menor será o conjunto de resultados. Quanto menor for o conjunto de resultados, mais direcionada e seletiva será sua consulta.
Usar marcas para categorizar itens de trabalho
Use marcas de item de trabalho para categorizar seus itens de trabalho em vez de um campo personalizado. As consultas que filtram em marcas geralmente têm um desempenho mais rápido em relação às consultas que filtram em correspondências de cadeia de caracteres.
Ao contrário de correspondências de campo personalizadas ou correspondências parciais, uma consulta com uma operação Tags Contains não requer uma verificação completa de todas as tabelas de itens de trabalho.
Usar Contains words para correspondências de cadeia de caracteres
Para filtrar uma correspondência de cadeia de caracteres, use o Contains Words em vez do operador Contains. O operador Contains Words executa uma pesquisa de texto completo no campo especificado, que tende a ser concluída mais rapidamente.
O operador Contains executa uma verificação de tabela, que é uma operação mais lenta do que o operador Contains Words. Ele também consome mais ciclos de CPU. Esses ciclos de CPU podem fazer você encontrar limitações de taxa. Para obter mais informações, consulte Taxa e limites de uso.
Especificar pequenos grupos com o operador In Group
O operador In Group filtra itens de trabalho com base em correspondências dentro de um grupo de valores. O grupo de valores corresponde aos valores contidos em uma equipe, grupo de segurança ou categoria de acompanhamento de trabalho. Por exemplo, você pode criar uma consulta para localizar todos os itens de trabalho que estão atribuídos a qualquer membro de uma equipe. Ou encontre todos os itens de trabalho que pertencem à categoria de requisitos (Microsoft.RequirementCategory).
Quando você filtra em um grupo que contém um grande número de membros, seu conjunto de resultados tende a ser maior e não seletivo. Além disso, se um grupo corresponder a um grande grupo do Microsoft Entra, a consulta gerará um custo bastante grande para resolver esse grupo do Microsoft Entra ID.
Evitar o uso de operadores negados
Operadores negados, como <>, Not In, Not Under, Not In Group, tendem a gerar consultas não seletivas e grandes conjuntos de resultados.
Use apenas operadores negados quando necessário. Sempre tente encontrar alternativas primeiro. Por exemplo, se Field1 tiver valores A, B, C, D; especifique a cláusula Field1 In A, B, C, em vez da cláusula negada Field1 <> D.
Evitar comparações de cadeias de caracteres
Consultas que contêm comparações de cadeia de caracteres geram verificações de tabela inerentemente ineficientes. Em vez disso, recomendamos que você use marcas ou um campo personalizado específico como alternativas, especialmente quando uma consulta tem um desempenho ruim.
Limitar operadores Or
Limite o número de operadores Or definidos em sua consulta. As consultas são executadas melhor quando menos operadores Or são usados. Muitos operadores Or podem tornar sua consulta não seletiva. Se a consulta for executada lentamente, reordene a cláusula do operador Or para a parte superior das cláusulas de consulta.
Salvar a sua consulta
Devido a otimizações internas, as consultas salvas tendem a ter melhor desempenho em relação a consultas não salvas. Sempre salve sua consulta quando você planeja reutilizá-la. Mesmo para consultas WIQL executadas por meio de uma API REST, salve o WIQL por meio do portal da Web para fazer suas chamadas à API REST, para que elas estejam menos propensas a regressões de desempenho no futuro.
Executar a sua consulta
Às vezes, você precisa executar sua consulta algumas vezes para alcançar o plano de otimização correto. Salve sua consulta e execute-a até 10 vezes durante um período de 30 minutos. Dessa forma, o sistema pode examinar a sua consulta e procurar o plano de otimização mais apropriado para ela.
Artigos relacionados
Comentários
Em breve: ao longo de 2024, vamos eliminar problemas do GitHub como o mecanismo de comentários para conteúdo e substituí-lo por um novo sistema de comentários. Para obter mais informações, consulte: https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de