Consultar campos, operadores e macros no Azure Boards
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Aqui, você encontrará descrições detalhadas de cada tipo de dados de campo, operadores de consulta e macros de consulta. Alguns tipos de dados, operadores e macros são válidos apenas para a versão indicada do Azure DevOps.
Para ver uma referência rápida de tarefas de consulta e operadores e macros com suporte para cada tipo de dados, confira Referência rápida de consulta. Confira também Criar uma consulta/Melhores práticas.
Valores e tipos de dados do campo de consulta
O valor especificado para um campo deve estar em conformidade com o tipo de dados para esse campo. A tabela a seguir lista tipos de dados compatíveis:
Observação
Para o serviço de nuvem do Azure Boards, o tipo de dados corresponde ao listado para o campo na página Processo>Campos. Para implantações locais, o tipo de dados corresponde ao atributo type atribuído a uma FIELD definição. Para obter mais informações, consulte Campos e atributos de campo de itens de trabalho.
Data type
Descrição
Booliano
Especifica um campo que assume um valor Verdadeiro/Falso.
DateTime ou Date/Time
Um campo de data no qual você pode especificar uma variável, como @Today ou @Today-1, ou um valor, como 1/1/2023. Insira datas no Padrão de Data definido para seu perfil pessoal. (Confira Definir preferências pessoais para ver detalhes.) Para obter exemplos de consulta, confira Query by date or @CurrentIteration.
Para consultas WIQL, você também pode especificar a data no padrão UTC (Tempo Universal Coordenado). Para obter mais informações, confira Sintaxe para a Work Item Query Language (WIQL).
Double ou Decimal
Um número real, como 0,2 ou 3,5. Para ver exemplos de consulta, confira Consultar por campos numéricos.
GUID
Uma cadeia de caracteres que representa uma ID exclusiva.
Histórico
Campo com formatação personalizada usado para acompanhar informações históricas. Esse tipo de dados é usado somente para oferecer suporte ao campo Histórico. Esse campo é indexado automaticamente para a pesquisa de texto completo quando esse tipo de pesquisa está disponível. Consulte Pesquisas de texto completo e palavras parciais, descritas posteriormente neste artigo. Para obter exemplos de consulta, consulte Histórico e auditoria.
HTML
Cadeias de texto que dão suporte a descrições formatadas, como os campos Descrição ou Etapas de Reprodução. Esses campos são indexados automaticamente para a pesquisa de texto completo quando esse tipo de pesquisa está disponível. Consulte Pesquisas de texto completo e palavras parciais, descritas posteriormente neste artigo. Para consultar campos de rich text, consulte Consultar por títulos, IDs e campos de rich text.
Identidade
Cadeia de caracteres de texto curto que identifica uma identidade de usuário.
Inteiro
Um número inteiro de 32 bits com sinal, como 0, 1, 2 ou 34.
PlainText ou Campo de texto (várias linhas)
Cadeias de texto com suporte para descrições longas, como o campo Informações de Inicialização do Aplicativo. Esses campos são indexados automaticamente para a pesquisa de texto completo quando esse tipo de pesquisa está disponível. Consulte Pesquisas de texto completo e palavras parciais, descritas posteriormente neste artigo. Para consultar campos de tetxo simples, consulte Consultar por títulos, IDs e campos de rich text.
picklistDouble1
Campo personalizado definido para conter uma lista de seleção de valores decimais.
picklistInteger1
Campo personalizado definido para conter uma lista de seleção de valores inteiros.
picklistString1
Campo personalizado definido para conter uma lista de seleção de valores de cadeia de caracteres de texto curto (255 caracteres ou menos).
Cadeia de caracteres ou Campo de texto (linha única)
Uma cadeia de texto curto que contém até 255 caracteres Unicode. Os campos de texto de cadeia de caracteres geralmente são usados para dar suporte a listas de seleção ou menus suspensos.
TreePath
Uma estrutura de árvore de ramificação, como um caminho de Área ou Iteração. Escolha um item em uma lista de valores válidos. Localize itens de trabalho iguais, não iguais, sob ou não sob uma estrutura de árvore, ou use os operadores In ou Not In para especificar vários valores. Defina a estrutura de árvore de um projeto — caminhos de área e caminhos de iteração — e selecione os que deseja associar a uma equipe.
Para obter mais informações sobre como construir consultas, consulte Consultar por área ou caminho de iteração ou Consultar por data ou iteração atual.
Observação
- Os tipos de dados lista de seleção... são atribuídos apenas a campos personalizados definidos para um processo herdado. O modelo de processo Herdado só tem suporte para o Azure DevOps Services e o Azure DevOps Server 2019.
Padrão de data e hora
O padrão de data e hora inserido para campos DateTime deve corresponder ao selecionado em seu perfil. Para exibir ou alterar sua seleção, confira Definir preferências do usuário de Hora e Localidade.
Operadores de consulta
Você pode usar os operadores de consulta da seguinte tabela para especificar como cada valor em uma cláusula deve se relacionar ao valor correspondente em um item de trabalho. Para obter informações sobre o tipo de dados atribuído a campos de itens de trabalho, consulte Referência de campos de item de trabalho.
Para saber mais sobre como adicionar cláusulas e usar os operadores And/Or, consulte Definir uma consulta.
Operador de consulta
Retorna itens de trabalho se o valor no item de trabalho corresponder aos critérios listados
Tipos de dados aplicáveis
=
Corresponde ao valor na cláusula.
Número — que inclui Double, GUID, Inteiro — e Cadeia de caracteres, DateTime e TreePath
<>
Não corresponde ao valor na cláusula.
Número, Cadeia de caracteres, DateTime e TreePath
>
É maior que o valor na cláusula.
Número, Cadeia de caracteres e DateTime
<
É menor que o valor na cláusula.
Número, Cadeia de caracteres e DateTime
>=
É maior ou igual ao valor na cláusula.
Número, Cadeia de caracteres e DateTime
<=
É menor ou igual ao valor na cláusula.
Número, Cadeia de caracteres e DateTime
=[campo]
Corresponde ao valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
<>[campo]
Não corresponde ao valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
>[campo]
É maior que o valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
<[campo]
É menor que o valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
>=[campo]
É maior ou igual ao valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
<=[campo]
É menor ou igual ao valor contido no campo especificado.
Número de um campo com o mesmo tipo de dados que o campo especificado
Contém
Contém uma correspondência exata ou parcial da cadeia de texto dentro do campo selecionado para filtragem.
Cadeia de caracteres
Não contém
Não contém uma correspondência exata ou parcial da cadeia de texto dentro do campo selecionado para filtragem.
Cadeia de caracteres
Contém Palavras
Contém a cadeia de texto ou as palavras exatas dentro do campo selecionado para filtragem. Você também pode inserir palavras ou frases parciais que contenham o caractere curinga, *. A cadeia de caracteres de texto está limitada a 100 caracteres. Para conhecer as restrições, consulte Pesquisas de texto completo para obter os requisitos de servidor e ordenação.
Campos de texto longo indexados para pesquisa de texto completo, que correspondem a todos os campos PlainText e HTML, e os campos Histórico e Título.
Não Contém Palavras
Não contém a cadeia de texto ou as palavras exatas dentro do campo selecionado para filtragem. A cadeia de caracteres de texto está limitada a 100 caracteres.
Use esse operador em combinação com uma cláusula com o operador Contém Palavras para incluir e excluir palavras-chave específicas.
Campos de texto são indexados para a pesquisa de texto completo.
In
Corresponde a qualquer valor no conjunto delimitado. Por exemplo, você pode encontrar itens de trabalho cujos IDs sejam 100, 101 e 102 se especificar esses valores para o campo ID. Separe os valores com o separador de lista correspondente às configurações regionais definidas para seu computador cliente. Por exemplo, você pode usar uma vírgula (,).
Número, Cadeia de caracteres, DateTime, TreePath
Está Vazio
Lista itens de trabalho que contêm um campo HTML vazio. Você não especifica um valor com esse operador. Esse operador tem suporte para o Azure Boards (serviço de nuvem), Azure DevOps Server 2019 e versões posteriores.
HTML
Não Está Vazio
Lista itens de trabalho que têm algum conteúdo no campo HTML. Você não especifica um valor com esse operador. Esse operador tem suporte para o Azure Boards (serviço de nuvem), Azure DevOps Server 2019 e versões posteriores.
HTML
Não está em
Não corresponde a nenhum valor no conjunto delimitado. Você pode excluir itens de trabalho cujos estados não são Resolvido, Concluído ou Fechado dos resultados da consulta se você especificar esses valores para o campo Estado. Separe os valores com o separador de lista correspondente às configurações regionais definidas para seu computador cliente. Por exemplo, você pode usar uma vírgula (,).
O operador Não Em está disponível no Azure Boards e no TFS 2018.2 e versões posteriores.
Número, Cadeia de caracteres, DateTime, TreePath
In Group
Corresponde a um valor que é um membro do grupo na cláusula. Os grupos correspondem ao nome de 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 aos membros do grupo Colaboradores ou a uma equipe. Grupos de equipe são criados ao criar uma equipe. O nome dos grupos da equipe segue o padrão [Nome do Projeto da Equipe]\Nome da Equipe.
Para ver exemplo de consultas, confira Consultar por atribuição ou alterações de fluxo de trabalho.
Cadeia de caracteres que corresponde ao nome de uma equipe, grupo de segurança ou categoria definida no sistema.
Observação
Você pode usar o operador Em Grupo somente com campos que usam o tipo de dados Cadeia de Caracteres ou o campo Tipo do Item de Trabalho. Você também pode usar grupos definidos no Microsoft Entra ID quando sua conta do Azure Boards é apoiada pelo Microsoft Entra ID ou pelo Active Directory quando a instância do servidor local é apoiada pelo Active Directory.
Para obter informações sobre grupos de categorias, consulte Usar categorias para agrupar tipos de item de trabalho.
Not in Group
Não corresponde a um valor que é um membro do grupo na cláusula.
Cadeia de caracteres que corresponde ao nome de um grupo do usuário no Team Foundation Server ou a um grupo da categoria definido para um projeto da equipe.
Observação
Você pode usar o operador Não Em Grupo somente com campos que usam o tipo de dados Cadeia de Caracteres ou o campo Tipo do Item de Trabalho. Você também pode usar grupos definidos no Microsoft Entra ID quando sua conta do Azure Boards é apoiada pelo Microsoft Entra ID ou pelo Active Directory quando a instância do servidor local é apoiada pelo Active Directory.
Not Under
Não corresponde ao valor na cláusula e não é contido pelo nó na cláusula.
TreePath
Sob
Corresponde ao valor na cláusula ou é contido pelo nó na cláusula.
TreePath
Was Ever
Corresponde ao valor na cláusula em qualquer ponto anterior.
Cadeia de caracteres , DateTime
Observação
Não há suporte para Was Ever em campos de data ao usar o Editor de Consultas. Ele só têm suporte ao fazer um WIQL direto.
Dica
É possível construir uma consulta usando a sintaxe WIQL que usa um operador, como Was Ever, para outros campos de tipo de dados que os listados. Por exemplo, você pode usar Já Foi dentro de uma cláusula usando o Caminho de Iteração. Para obter um exemplo, confira Consultar por data ou iteração atual, Listar itens de trabalho removidos de um sprint.
Consultar macros ou variáveis
Você pode usar as macros descritas na tabela a seguir para filtrar consultas com base em campos específicos.
Observação
As macros a seguir só têm suporte no portal da Web: @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity e @TeamAreas. As consultas que contêm essas macros não funcionarão quando abertas no Visual Studio/Team Explorer, Microsoft Excel ou Microsoft Project.
Macro
Descrição
[Qualquer]
Use com os campos Tipo de Item de Trabalho ou Estado para pesquisar em todos os tipos de item de trabalho ou em todos os estados. Por exemplo, Work Item Type=[Any] não usará filtros com base no tipo de item de trabalho.
@CurrentIteration
Use com o campo Caminho da Iteração para filtrar automaticamente itens de trabalho atribuídos ao sprint atual com base no foco ou contexto da equipe atual. Para obter exemplos específicos, consulte Consultar por data ou iteração atual.
A macro @CurrentIteration só funciona quando executada no portal da Web. Você não pode usar a macro ao copiar ou clonar conjuntos de testes e casos de teste, definir alertas ou com APIs REST.
@CurrentIteration +/- n
Use com o campo Caminho da Iteração para filtrar o conjunto de itens de trabalho atribuídos ao sprint atual +/- n sprints com base no foco ou contexto da equipe atual. Para obter exemplos específicos, consulte Consultar por data ou iteração atual.
A macro @CurrentIteration +/- n tem suporte para o Azure Boards, o Azure DevOps Server 2019 e versões posteriores e somente quando executada no portal da Web.
@Follows
Use com o campo ID e o operador In para listar todos os itens de trabalho que você está seguindo no projeto. Para saber mais sobre o recurso Seguir, consulte Seguir um item de trabalho ou uma solicitação de pull. Você pode exibir essa mesma lista na página Itens de Trabalho, exibição dinâmica Seguindo.
A macro @Follows só tem suporte quando executada no portal da Web.
@Me
Use com um campo de identidade ou de conta de usuário para pesquisar automaticamente itens associados ao seu nome de usuário ou conta. Por exemplo, você pode encontrar itens de trabalho que você abriu com a cláusula Created By=@Me. Para obter mais exemplos, consulte Consultar por atribuição, fluxo de trabalho ou alterações de quadro Kanban.
@MyRecentActivity1
Use com o campo ID e o operador Em para listar itens de trabalho que você visualizou ou atualizou no projeto nos últimos 30 dias. Você pode exibir essa mesma lista na página Itens de Trabalho, exibição dinâmica Minha atividade.
@Project
Use com o campo Projeto de Equipe para filtrar itens de trabalho em outros projetos. Por exemplo, você pode encontrar todos os itens de trabalho no projeto selecionado no momento usando a cláusula Team Project=@Project. O sistema usa automaticamente como padrão a filtragem com base no projeto atual. Para obter mais informações, confira Definir uma consulta, consultar entre projetos.
@RecentMentions1
Use com o campo ID e o operador Em para listar os itens de trabalho em que você foi mencionado na seção Discussão. Você pode exibir essa mesma lista na página Itens de Trabalho, exibição dinâmica Mencionado.
@RecentProjectActivity1
Use com o campo ID e o operador Em para listar itens de trabalho que foram atualizados recentemente. O número de itens de trabalho listados depende da atividade de acompanhamento de trabalho do projeto. Para projetos altamente ativos, a macro lista itens de trabalho que foram atualizados no projeto nos últimos 30 dias ou mais. No entanto, para projetos menos ativos, essa lista pode incluir itens de trabalho com mais de 30 dias. Você pode exibir listas semelhantes na página Itens de Trabalho, exibições dinâmicas Criados recentemente, Atualizados recentemente e Concluídos recentemente. O número de itens de trabalho retornados é limitado a 5000.
@StartOfDay2
Use com um campo DateTime para filtrar itens de trabalho relacionados à data atual ou com um deslocamento de adição/subtração. Por exemplo, você pode encontrar todos os itens fechados na última semana com a cláusula Closed Date>=@StartOfDay-7. Para obter mais exemplos, consulte Consultar por data ou iteração atual.
@StartOfMonth2
Use com um campo DateTime para filtrar itens de trabalho relacionados ao mês atual ou com um deslocamento de adição/subtração. Por exemplo, você pode encontrar todos os itens criados nos últimos três meses com a cláusula Created Date>=@StartOfMonth-3. Para obter mais exemplos, consulte Consultar por data ou iteração atual.
@StartOfWeek2
Use com um campo DateTime para filtrar itens de trabalho relacionados à semana atual ou com um deslocamento de adição/subtração. Por exemplo, você pode encontrar todos os itens alterados nas últimas duas semanas com a cláusula Changed Date>=@StartOfWeek-2. Para obter mais exemplos, consulte Consultar por data ou iteração atual.
@StartOfYear2
Use com um campo DateTime para filtrar itens de trabalho relacionados ao ano atual ou com um deslocamento de adição/subtração. Por exemplo, você pode encontrar todos os recursos que têm uma Data de Destino agendada no ano atual com a cláusula Target Date>=@StartOfYear. Para obter mais exemplos, consulte Consultar por data ou iteração atual.
@TeamAreas
Use apenas com o campo Caminho da Área para filtrar itens de trabalho cujo caminho de área corresponde a um atribuído a uma equipe específica. Exige que você use o operador =. Por exemplo, você pode encontrar todos os itens atribuídos aos caminhos de área atribuídos à equipe da Web com a cláusula Area Path=@TeamAreas [Fabrikam Fiber]\Web. Para obter mais exemplos, confira Consultar por área ou caminho de iteração.
A macro @TeamAreas tem suporte para o Azure DevOps Server 2019 e versões posteriores e somente quando executada no portal da Web.
@Today
Use com um campo DateTime para filtrar itens de trabalho relacionados à data atual ou com uma data anterior. Também é possível modificar a macro @Today subtraindo dias. Por exemplo, você pode encontrar todos os itens criados na última semana com a cláusula Created Date>=@Today-7. Para obter mais exemplos, consulte Consultar por data ou iteração atual.
Observação
- As macros @MyRecentActivity, @RecentMentions e @RecentProjectActivity são compatíveis com o TFS 2018.2 e versões posteriores.
- As macros @StartOfDay, @StartOfWeek, @StartOfMonth e @StartOfYear têm suporte para o Azure DevOps Server Atualização 1 de 2019 e versões posteriores.
Pesquisas de texto completo e palavras parciais
Especifique Contém ou Não Contém para realizar uma pesquisa relativa a correspondências exatas ou parciais de uma palavra ou frase. Esses operadores filtram itens com base no índice de pesquisa de texto completo criado para campos de texto longo. Escolha Contém Palavras ou Não Contém Palavras para realizar uma pesquisa relativa a uma frase exata ou para usar o caractere curinga *. Esses operadores usam o índice de pesquisa de texto completo. Você pode usar somente o caractere curinga no final de uma palavra ou frase parcial.
Para obter exemplos, consulte Exemplo de consultas de item de trabalho e Consultar itens de trabalho usando o campo Histórico.
Observação
Nem todas as implantações são compatíveis com pesquisas de texto completo. Por exemplo, o SQL Express e o SQL Azure, que dão suporte ao serviço de nuvem, não dão suporte à pesquisa de texto completo. Nesses casos, você só vê os operadores Contém e Não contém.
O Azure DevOps Server e o Team Foundation Server indexam automaticamente todos os campos de texto longo com um tipo de dados de campos Texto sem formatação, HTML e Título para a pesquisa de texto longo. O índice e os operadores estarão disponíveis somente quando o SQL Server que dá suporte ao Team Foundation Server der suporte à pesquisa de texto completo.
As pesquisas de texto completo exigem uma ordenação SQL que corresponda a uma linguagem com um separador de palavras registrado no SQL Server. Se as configurações de ordenação do banco de dados de ordenação do projeto usado para sua instância do Team Foundation Server não for correspondente a uma linguagem com suporte, seus resultados de pesquisa podem não corresponder às suas expectativas. Nesses casos, você pode tentar usar os operadores Contém ou Não Contém.
Para obter mais informações, confira Consultas de pesquisa de texto completo e configurações de ordenação.
Artigos relacionados
- Referência rápida de consulta
- Sobre consultas gerenciadas
- Índice de campos de item de trabalho
- Sintaxe para o WIQL (Work Item Query Language)
API REST
Para interagir programaticamente com consultas, confira um destes recursos da API REST:
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de