Campos de consulta, operadores e macros

Azure DevOps Serviços | Azure DevOps Server | Azure DevOps Server 2022

Gorjeta

Primeira vez a fazer uma consulta? Comece com Definir uma consulta para passos procedurais ou Consultar uma referência rápida para exemplos.

Use este guia de referência para procurar tipos de dados de campo, operadores de consulta, macros e variáveis ao construir consultas no Editor do Power Query. Todos os operadores e macros são suportados no Azure Boards; alguns aplicam-se apenas a versões específicas do Azure DevOps Server.

Para obter exemplos rápidos e tarefas do editor, consulte Referência rápida de consulta e Gerenciar e organizar consultas.

Pré-requisitos

Categoria Requerimentos
Adesão ao projeto Tem de ser adicionado como membro do projeto.
Níveis de acesso - Para visualizar e executar consultas partilhadas: Deve ser membro do Project.
- Para adicionar e guardar uma consulta partilhada: Deve ter pelo menos acesso Básico.
Permissões Garante que a permissão Contribuir está definida como Permitir para a pasta onde queres adicionar uma consulta. A sua organização pode precisar de configurar manualmente o grupo Contributors para conceder esta permissão.

Nota

É necessário tanto um nível de acesso suficiente como uma permissão de Contribuição para guardar consultas partilhadas. O acesso básico não chega.

Categoria Requerimentos
Adesão ao projeto Tem de ser adicionado como membro do projeto.
Níveis de acesso - Para visualizar e executar consultas partilhadas: Deve ser membro do Project.
- Para adicionar e guardar uma consulta partilhada: Deve ter pelo menos acesso Básico.
Permissões Garante que a permissão Contribuir está definida como Permitir para a pasta onde queres adicionar uma consulta. A sua organização pode precisar de configurar manualmente o grupo Contributors para conceder esta permissão.

Nota

É necessário tanto um nível de acesso suficiente como uma permissão de Contribuição para guardar consultas partilhadas. O acesso básico não chega.

Tipos de dados e valores do campo de consulta

Especifique um valor que corresponda ao tipo de dado de um campo. A tabela seguinte lista os tipos de dados suportados:

Nota

Para Azure Boards (cloud), o tipo de dados corresponde ao campo mostrado na página Process > Fields. Para implantações locais, o tipo de dados corresponde ao type atributo em uma FIELD definição. Consulte Campos de item de trabalho e atributos de campo para obter detalhes.

Tipo de dados Description
Booleano Armazena um valor Verdadeiro/Falso.
DataHora ou Data/Hora Use uma variável de data (por exemplo, @Today ou @Today-1) ou uma data explícita como 01/01/2025. Insira as datas no padrão definido no seu perfil. Para obter exemplos de consulta, consulte Query by date or @CurrentIteration. Para consultas WIQL, você também pode especificar datas em UTC. Consulte Sintaxe da linguagem de consulta de itens de trabalho (WIQL).
Duplo ou decimal Armazena um número real, como 0,2 ou 3,5. Consulte Consulta por campos numéricos para obter exemplos.
GUID Armazena uma string de identificador único.
História Campo formatado personalizado usado para informações históricas (o campo Histórico ). Quando a pesquisa de texto completo está disponível, este campo é indexado para consultas de texto completo. Consulte Histórico e auditoria.
HTML Armazena texto formatado, como Descrição ou Passos de Reprodução. Quando a pesquisa de texto completo está disponível, esses campos são indexados. Para consultar campos de rich-text, consulte Consulta por títulos, IDs e campos de rich-text.
Identidade Armazena uma cadeia de caracteres de texto curta que identifica uma identidade de usuário.
Inteiro Armazena um inteiro assinado de 32 bits, como 0, 1, 2 ou 34.
Texto Simples ou Campo de Texto (múltiplas linhas) Armazena valores de texto longo, como Informação de Início de Aplicação. Estes campos são indexados para pesquisa de texto completo se suportado. Consulte Consulta por títulos, IDs e campos rich-text.
picklistDouble Campo personalizado que contém uma lista de escolhas de valores decimais.
picklistInteger Campo personalizado que contém uma lista de valores inteiros selecionados.
picklistString Campo personalizado que contém uma lista de opções de valores de texto curto (255 caracteres ou menos).
Campo de texto ou Campo de texto (uma linha) Armazena texto curto até 255 caracteres Unicode. As equipes geralmente usam esses campos para listas de opções ou menus suspensos.
TreePath Representa uma árvore ramificada, como Caminho de Área ou Caminho de Iteração. Escolha um valor de nó válido. Pode filtrar por igualdade, desigualdade, "Inferior a" ou "Não inferior a". Use os operadores In e Not In para especificar múltiplos valores. Defina estruturas em árvore para um projeto – caminhos de área e caminhos de iteração – e selecione os nós a associar às equipas. Para exemplos de consulta, consulte Consulta por área ou caminho de iteração e Consulta por data ou iteração atual.

Nota

Os picklist... tipos só se aplicam a campos personalizados definidos para um processo herdado.

Padrão de data e hora

O padrão de data e hora que você insere para os campos DateTime deve corresponder ao que você selecionou através do seu perfil. Para ver ou alterar a sua seleção, consulte Definir preferências do utilizador.

Captura de tela mostrando as opções no menu suspenso de Padrão de Data no painel de Hora e Localidade. Captura de tela mostrando as opções no menu suspenso de Padrão de Hora no painel de Hora e Localidade.

Captura de tela que mostra o painel Hora e localidade com os campos Padrão de data e Padrão de hora.

Operadores de consulta

Use operadores para definir como um valor de cláusula deve se relacionar com o valor de campo de um item de trabalho. Para tipos de dados de campo, consulte Referência de campo de item de trabalho. Para obter ajuda na criação de consultas, consulte Definir uma consulta.

Operador de consulta Quando o operador retorna itens de trabalho correspondentes Tipos de dados aplicáveis
= Corresponde ao valor da cláusula. Número (Duplo/Decimal/GUID/Inteiro), String, DateTime, TreePath
<> Não corresponde ao valor da cláusula. Número, String, DateTime, TreePath
> É maior do que o valor da cláusula. Número, String, DateTime
< É menor do que o valor da cláusula. Número, String, DateTime
>= É maior ou igual ao valor da cláusula. Número, String, DateTime
<= É menor ou igual ao valor da cláusula. Número, String, DateTime
=[Campo] Corresponde ao valor em outro campo especificado (deve ser do mesmo tipo de dados). Nome de um campo do mesmo tipo de dados (campos booleanos comparam a igualdade com outros campos).
<>[Campo] Não corresponde ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
>[Campo] É maior que o valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
<[Campo] É menor que o valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
>=[Campo] É maior ou igual ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
<=[Campo] É menor ou igual ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
contém Contém uma correspondência de texto exata ou parcial. Cordão
Não contém Não contém uma correspondência de texto exata ou parcial. Cordão
Contém palavras Corresponde a uma frase ou palavras exatas (suporta o uso de um curinga no final *). Limite: 100 caracteres. Este operador usa indexação de texto completo; consulte a seção Texto completo neste artigo para obter os requisitos de servidor e agrupamento. Campos de texto longo indexados para pesquisa de texto completo (Texto Simples, HTML, Histórico e Título).
não contém palavras Exclui itens que contêm a frase ou palavras especificadas. Limite: 100 caracteres. Utilize cláusulas complementares com Contains Words para incluir ou excluir palavras-chave. Campos de texto indexados para pesquisa de texto completo.
In Corresponde a qualquer valor em um conjunto delimitado (use o separador de lista regional do sistema operacional, normalmente uma vírgula). Número, String, DateTime, TreePath
Está vazio Corresponde a itens em que um campo HTML não contém conteúdo (nenhum valor especificado). Suportado para Azure Boards e Azure DevOps Server. HTML
Não está vazio Corresponde a itens em que um campo HTML contém conteúdo. Suportado para Azure Boards e Azure DevOps Server. HTML
Não está em Exclui valores em um conjunto delimitado (use o separador de lista regional). Suportado para Azure Boards e Azure DevOps Server. Número, String, DateTime, TreePath
No Grupo Corresponde a valores que são membros de um grupo nomeado (equipe, grupo de segurança ou categoria). Por exemplo, use o grupo Colaboradores ou um grupo de equipe nomeado no padrão [Project Name]\Team Name. Consulte Consulta por atribuição ou alterações de fluxo de trabalho para obter exemplos. Use Em Grupo somente com campos do tipo "String" ou Tipo de Item de Trabalho. Pode usar grupos do Microsoft Entra ID quando a sua conta utiliza o Microsoft Entra ID, ou grupos do Active Directory para instalações locais. String (corresponde ao nome do grupo ou da equipe) ou Tipo de Item de Trabalho
Fora do grupo Exclui membros de um grupo nomeado. Cadeia de caracteres que corresponde a um grupo de usuários ou categoria de projeto.
Não embaixo Exclui itens iguais ou contidos no nó de árvore especificado. TreePath
Em Corresponde a itens iguais ou contidos no nó de árvore especificado. TreePath
Alguma vez foi Corresponde a um valor que um campo manteve em qualquer momento anterior. (Editor do Power Query: apenas campos de string. O suporte DateTime requer consultas WIQL diretas.) String, DateTime (Cadeia de caracteres, Data e Hora)

Gorjeta

Você pode construir consultas WIQL que usam operadores, Was Ever por exemplo, para outros tipos de dados como Caminho de Iteração. Consulte Listar itens de trabalho removidos de um sprint para ver um exemplo.

Exemplos comuns de operadores

Aqui estão exemplos de consultas representativas que utilizam vários operadores:

Query Returns
State = Active Itens de trabalho com estado "Ativo"
Priority <> Low Todos os itens, exceto os de baixa prioridade
Created Date >= @Today-7 Itens de trabalho criados nos últimos 7 dias
Assigned To = @Me Itens atribuídos ao utilizador atual
Tags Contains "frontend" Itens com uma etiqueta contendo "frontend"
State In (Active, In Progress) Itens em qualquer dos estados
Area Path Under "Project\Web" Todos os itens pertencem à área Web, incluindo subáreas
Assigned To In Group "[Project]\Developers" Itens atribuídos a qualquer pessoa do grupo de Desenvolvedores
Description Contains Words "urgent" Itens cuja descrição contém a palavra "urgente"

Pesquisas de texto completo e de palavras parciais

Use Contém ou Não Contém para pesquisar correspondências exatas ou parciais em campos de texto longo. Estes operadores utilizam o índice de consulta. Use Contém Palavras ou Não Contém Palavras para pesquisar frases exatas ou usar um curinga final (*). Estes operadores requerem o índice em texto completo.

Você pode usar o caractere curinga somente no final de uma palavra ou frase parcial. Para obter exemplos, consulte Exemplos de consultas de itens de trabalho e Consultas de itens de trabalho usando o campo Histórico.

Nota

Nem todas as implantações oferecem suporte à pesquisa de texto completo. Por exemplo, o SQL Express e algumas configurações de SQL na nuvem não oferecem suporte à pesquisa de texto completo. Nessas implantações, apenas os operadores Contém e Não Contém são visíveis.

Azure DevOps Server indexa campos de texto longo (Texto simples e HTML) e o campo Título para pesquisa em texto completo quando o SQL Server subjacente suporta indexação de texto completo.

A pesquisa de texto completo também requer um agrupamento SQL com um separador de palavras registrado para o idioma que você usa. Se a compilação da base de dados da coleção não corresponder a uma linguagem suportada, os resultados podem não corresponder às expectativas. Nesses casos, use Contém ou Não Contém em vez disso.

Para obter mais informações, consulte Consultas de pesquisa de texto completo e configurações de agrupamento.

Operadores de combinação

As consultas usam lógica AND para combinar múltiplas cláusulas. Cada cláusula adicional filtra ainda mais os resultados. Por exemplo:

  • State = Active AND Priority = High devolve os itens de trabalho que estejam ativos E tenham prioridade elevada.
  • State = Active AND State <> Closed devolve itens ativos excluindo aqueles marcados como fechados.
  • Assigned To = @Me AND State <> Done mostra os itens que lhe foram atribuídos e que não estão concluídos.

Pode usar parênteses para agrupar condições para consultas complexas na sintaxe direta WIQL:

  • (State = Active OR State = In Progress) AND Priority = High devolve itens de alta prioridade em estados ativos ou em progresso.

Para mais exemplos e detalhes da sintaxe WIQL, veja Sintaxe para a Linguagem de Consulta de Itens de Trabalho (WIQL).

Resolução de problemas e erros comuns

Problema Causa Provável Solução
Macro não retorna resultados @CurrentIteration funciona apenas em portal web; APIs REST e CLI podem devolver resultados vazios Use datas diretas em scripts ou APIs. Para alternativas, veja Consultar por data ou iteração atual.
@TeamAreas consulta devolve resultados inesperados A macro só funciona com o campo Caminho da Área; usá-la com outros campos não tem efeito Verifica se estás a filtrar pelo Caminho de Área. Use outros campos de caminho em árvore (Caminho de Iteração) com o operador Under em vez disso.
Erro do operador Contains Words A consulta ultrapassa o limite de 100 caracteres ou utiliza a colocação inválida de wildcard Reduza o texto da consulta para menos de 100 caracteres. Use o coringa apenas no final do período (por exemplo, feature*), não no início.
Na consulta de grupo falha O formato do nome do grupo está incorreto ou o grupo não existe Use o formato exato: Assigned To In Group "[Project]\\Team Name" para equipas. Verifique o nome do grupo nas definições do projeto.
Algum operador não estava a trabalhar nas datas Editor do Power Query não suporta Was Ever em campos DateTime Use sintaxe WIQL direta em vez de editor de consultas visual. Para obter mais informações, consulte Sintaxe para a linguagem de consulta de item de trabalho (WIQL).
A consulta de campo booleana não retorna resultados O valor distingue maiúsculas de minúsculas nas consultas WIQL Use o caso exato: CustomBoolField = True ou CustomBoolField = False (T/F maiúsculo em WIQL).

Consultar macros e variáveis

Utilize as macros seguintes para filtrar consultas dinamicamente.

Nota

As seguintes macros só são suportadas a partir do portal Web: @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivitye @TeamAreas. Consultas que contenham estas macros não funcionam quando abertas no Visual Studio/Team Explorer, Microsoft Excel ou Microsoft Project.

Macro Description
[Qualquer] Use com Tipo de Item de Trabalho ou Estado para pesquisar em todos os tipos ou estados. Por exemplo, Work Item Type=[Any] remove a filtragem baseada em tipo.
@CurrentIteration Use com o Caminho de Iteração para filtrar itens de trabalho no sprint atual com base no contexto da equipe atual. Consulte Consulta por data ou iteração atual para obter exemplos. @CurrentIteration funciona somente quando executado a partir do portal da Web (não em APIs REST ou algumas operações de cópia/clone).
@CurrentIteration +/- n Use com o caminho de iteração para incluir sprints relativos à iteração atual (por exemplo, @CurrentIteration-1 ou @CurrentIteration+2). Suportado no portal web para Azure Boards e Azure DevOps Server.
@Follows Use com ID e o In operador para listar os itens de trabalho que você segue no projeto. Veja como seguir um item de trabalho ou pull request. Esta macro funciona apenas a partir do portal web.
@Me Use com campos de identidade para filtrar itens vinculados à sua conta (por exemplo, Created By=@Me). Consulte Consulta por atribuição, fluxo de trabalho ou alterações no quadro.
@MyRecentActivity Utilize com ID e In para listar os itens de trabalho que visualizou ou atualizou nos últimos cerca de 30 dias. Consulte a página Itens de Trabalho no separador A minha atividade com a mesma lista.
@Project Use com Team Project para filtrar itens de trabalho no projeto atual (por exemplo, Team Project=@Project). Consulte Consulta entre projetos.
@RecentMentions Usa com ID e In para listar itens de trabalho onde tu és mencionado nas Discussões. Consulte a página Itens de Trabalho Pivô mencionado .
@RecentProjectActivity Use ID e In para listar itens de trabalho recentemente atualizados em todo o projeto. A macro retorna até 5.000 itens; A janela real depende da atividade do projeto.
@StartOfDay Use com campos DateTime para filtrar em relação a hoje (por exemplo, Closed Date>=@StartOfDay-7).
@StartOfMonth Use com campos DateTime para filtrar em relação ao início do mês (por exemplo, Created Date>=@StartOfMonth-3).
@StartOfWeek Use com campos DateTime para filtrar em relação ao início da semana (por exemplo, Changed Date>=@StartOfWeek-2).
@StartOfYear Use com campos DateTime para filtrar em relação ao início do ano (por exemplo, Target Date>=@StartOfYear).
@TeamAreas Use apenas com Caminho da Área e o operador = para localizar itens atribuídos aos caminhos de área de uma equipa (por exemplo, Area Path=@TeamAreas [Fabrikam Fiber]\Web). Suportado no portal web para Azure Boards e Azure DevOps Server.
@Today Use com campos DateTime para filtrar em relação a hoje (por exemplo, Created Date>=@Today-7). Consulte Consulta por data ou iteração atual.

Exemplos macro comuns

Aqui estão exemplos de consultas representativas que usam macros para tornar as consultas dinâmicas:

Query Devoluções (Portal web)
Iteration Path = @CurrentIteration Itens de trabalho no sprint atual
Iteration Path = @CurrentIteration-1 Itens de trabalho no sprint anterior
Assigned To = @Me Itens atribuídos ao utilizador atual
Created Date >= @Today-30 Itens criados nos últimos 30 dias
State = Active AND Area Path = @TeamAreas [Project]\MyTeam Itens ativos na área da tua equipa
Work Item Type = [Any] Todos os tipos de itens de trabalho (remove a filtragem por tipo)
Assigned To In Group @Follows Itens atribuídos a pessoas que segues

Nota

Macros como @CurrentIteration, @Me, @Follows, e @TeamAreas funcionam apenas no portal web. Para APIs REST, CLI e Power BI, utilize datas explícitas e IDs de utilizador em vez disso. Para alternativas, veja Consultar por data ou iteração atual.

Conteúdo relacionado

API REST

Para interagir programaticamente com consultas, consulte um destes recursos da API REST:

  • Last updated on