Partilhar via


Referência da sintaxe da Linguagem de Consulta do Item de Trabalho (WIQL)

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

Você pode usar a sintaxe WIQL para definir uma consulta como um hiperlink ou ao usar a API REST (Linguagem de Consulta de Item de Trabalho).

O WIQL suporta todas as funções disponíveis através do portal web Query Editor e mais algumas mais. Você pode especificar os campos a serem retornados e o agrupamento lógico das cláusulas de consulta. Você também pode usar uma ASOF cláusula para filtrar com base em atribuições de uma data anterior.

Important

A sintaxe WIQL é usada para executar a API REST Query By Wiql. A API retorna apenas IDs de item de trabalho, independentemente dos campos incluídos na SELECT instrução. Para obter informações completas, (1) obtenha os IDs do WIQL e, em seguida, (2) obtenha os itens de trabalho através de Obter uma lista de itens de trabalho por ID e para campos específicos.

Prerequisites

Category Requirements
Permissions Exibir itens de trabalho ou Exibir itens de trabalho neste nó permissão definida como Permitir. Essas permissões geralmente são concedidas aos membros dos grupos Leitores e Colaboradores para cada projeto de equipe. Para obter mais informações, consulte Permissões e grupos.

Visão geral da linguagem de consulta

WIQL tem cinco partes, conforme mostrado no trecho de sintaxe a seguir e descrito na tabela. A sintaxe WIQL não diferencia maiúsculas de minúsculas.

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2025'

Tip

Ao instalar a extensão Wiql Editor Marketplace, você pode construir consultas usando o Editor de Consultas e exibir a sintaxe WIQL. Em seguida, você pode copiar e modificar a sintaxe WIQL e executar a consulta usando o hub Wiql Playground adicionado aos painéis.

Cláusula Exemplo/Descrição
SELECT Identifica os campos a serem retornados para cada item de trabalho. Você pode especificar o nome amigável ou o nome de referência. Use colchetes ([]) se o nome contiver espaços em branco ou pontos.
FROM Indica se você deseja que a consulta localize itens de trabalho ou links entre itens de trabalho.
- Use FROM WorkItems para devolver itens de trabalho.
- Use FROM workItemLinks para retornar links entre itens de trabalho. Para obter mais informações, consulte Consultas para links entre itens de trabalho.
WHERE Especifica os critérios de filtro para a consulta. Para obter mais informações, consulte Condições de filtro (WHERE).
ORDER BY Especifica a ordem de classificação dos itens de trabalho retornados. Você pode especificar Ascendente (Asc) ou Descendente (Desc) para um ou mais campos. Por exemplo: ORDER BY [State] Asc, [Changed Date] Desc
ASOF Especifica uma consulta histórica indicando uma data para quando o filtro deve ser aplicado. Por exemplo, essa consulta retorna todas as histórias de usuário que foram definidas como Ativas em 11 de fevereiro de 2025. Especifique a data de acordo com as orientações fornecidas em Padrão de data e hora.
ASOF '02-11-2025'

Note

As consultas WIQL feitas em Painéis do Azure não devem exceder 32 K caracteres. O sistema não permite que você crie ou execute consultas que excedam esse comprimento.

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 que mostra as opções suspensas Padrão de Data no painel Hora e Localidade. Captura de tela que mostra as opções suspensas Padrão de Tempo no painel 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.

Literais de citação (aspas simples ou duplas são suportadas) DateTime usados em comparações. Eles devem estar no formato .NET DateTime do computador cliente local que executa a consulta. A menos que um fuso horário seja especificado, DateTime os literais estão no fuso horário do computador local.

WHERE 
   AND [System.ChangedDate] >= '01-18-2025 GMT'
   AND ([Closed Date] < '01-09-2025 GMT'
   OR [Resolved Date] >= '01-18-2025 14:30:01')  

Quando a hora é omitida em um DateTime literal e o parâmetro é igual a dayPrecision false, a hora é assumida como zero (meia-noite). A configuração padrão para o dayPrecision parâmetro é false.

Ou, você pode especificar o formato ISO 8601, que é válido independentemente da localidade. A ISO 8601 representa a data e a hora começando com o ano, seguido pelo mês, o dia, a hora, os minutos, segundos e milissegundos. Por exemplo, 2025-12-10 15:00:00.000 representa o dia 10 de dezembro de 2025 às 15h no horário local. Um exemplo de utilização do formato ISO 8601 é o seguinte:

WHERE 
   AND [System.ChangedDate] >= '2025-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2025-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2025-01-18T00:00:00.0000000')  

Campos personalizados

Você pode adicionar um campo personalizado a uma cláusula de consulta. Com WIQL, você deve especificar o nome de referência para o campo personalizado. Para projetos que usam um modelo de processo herdado, os campos personalizados geralmente são rotulados com Custom. prepended para seu nome e espaços removidos. Por exemplo:

Nome amigável Nome de referência
Approver Custom.Approver
Request Type Custom.RequestType
Scope Estimate Custom.CustomEstimate

Para projetos que usam o modelo de processo XML local, o nome de referência é definido pelas definições de tipo de item de trabalho XML.

Para obter mais informações, consulte Campos e atributos de item de trabalho.

Especificar cláusulas de filtro (WHERE)

A WHERE cláusula especifica os critérios de filtro. A consulta retorna somente itens de trabalho que satisfazem os critérios especificados. Por exemplo, a cláusula de exemplo WHERE a seguir retorna histórias de usuário que estão ativas e que são atribuídas a você.

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

Você pode controlar a ordem na qual os operadores lógicos são avaliados colocando-os entre parênteses para agrupar os critérios de filtro. Por exemplo, para retornar itens de trabalho atribuídos a você ou que você fechou, use o exemplo a seguir.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

Condições do filtro

Cada condição do filtro é composta por três partes, cada uma das quais deve obedecer às seguintes regras:

  • Campo: Você pode especificar o nome de referência ou o nome amigável. Os exemplos a seguir são sintaxe WIQL válida:
    • Nome de referência: SELECT [System.AssignedTo] ...
    • Nome amigável com espaços: SELECT [Assigned To] ...
    • Os nomes sem espaços não requerem colchetes: SELECT ID, Title ...
  • Operador: Os valores válidos são especificados na seção Operadores mais adiante neste artigo.
  • Valor do campo: Você pode especificar um dos três valores a seguir dependendo do campo especificado.
    • Um valor literal deve corresponder ao tipo de dados do valor do campo.
    • Uma variável ou macro que indica um determinado valor. Por exemplo, @Me indica a pessoa que está executando a consulta. Para obter mais informações, consulte Macros e variáveis.
    • O nome de outro campo. Por exemplo, você pode usar [Assigned to] = [Changed by] para localizar itens de trabalho atribuídos à pessoa que alterou o item de trabalho mais recentemente.

Para obter uma descrição e nomes de referência de todos os campos definidos pelo sistema, consulte Índice de campo de item de trabalho.

Operators

As consultas usam expressões lógicas para qualificar conjuntos de resultados. Estas expressões lógicas formam-se por uma ou mais operações conjuntas.

Algumas operações de consulta simples são as seguintes:

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

A tabela a seguir resume todos os operadores suportados para diferentes tipos de campo. Para obter mais informações sobre cada tipo de campo, consulte Campos e atributos de item de trabalho.

Os =operadores , <>, >, <, >=, e funcionam <= conforme o esperado. Por exemplo, System.ID > 100 consultas para todos os itens de trabalho com um ID maior que 100. System.ChangedDate > '01-01-25 12:00:00' consultas para todos os itens de trabalho alterados após o meio-dia de 1º de janeiro de 2025.

Além desses operadores básicos, existem alguns comportamentos e operadores específicos para determinados tipos de campo.

Note

Os operadores disponíveis dependem da sua plataforma e versão. Para obter mais informações, consulte Referência rápida de consulta.

Tipo de campo Operadores suportados
Boolean = , <> , =[Field] , <>[Field]
DateTime = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Double, GUID, Integer = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Identity = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
PlainText Contains Words, Not Contains Words, Is Empty, Is Not Empty
String = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever
TreePath =, <>, In, Not In, Under, Not Under

Agrupamentos lógicos

Você pode usar os termos AND e OR no sentido booleano típico para avaliar duas cláusulas. Você pode usar os termos AND EVER e OR EVER ao especificar um WAS EVER operador. Você pode agrupar expressões lógicas e juntá-las ainda mais, conforme necessário. Os exemplos a seguir demonstram.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

Você pode negar os containsoperadores , undere in usando not. Você não pode negar o ever operador. O exemplo a seguir consulta todos os itens de trabalho que não estão atribuídos na subárvore de Fabrikam Fiber\Account Management.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

Exemplo de consulta, já foi atribuído a

O exemplo do Editor de Consultas a seguir localiza todos os itens de trabalho que já foram atribuídos a Jamal Hartnett.

Captura de tela do Editor de Consultas, consulta de lista simples, já foi atribuída.

A sintaxe WIQL correspondente é a seguinte:

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

Macros ou variáveis

A tabela a seguir lista as macros ou variáveis que você pode usar em uma consulta WIQL.

Macro Usage
@Me Use essa variável para procurar automaticamente o alias do usuário atual em um campo que contenha aliases de usuário. Por exemplo, você pode encontrar itens de trabalho abertos se definir a coluna como Field, a Activated By coluna como Operatore a = coluna como Value.@Me
@CurrentIteration Use essa variável para filtrar automaticamente os itens de trabalho atribuídos ao sprint atual para a equipe selecionada com base no contexto da equipe selecionada.
@Project Use essa variável para procurar itens de trabalho no projeto atual. Por exemplo, você pode encontrar todos os itens de trabalho no projeto atual se definir a coluna como Field, a Team Project coluna como Operatore a = coluna como Value.@Project
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear
Use essas macros para filtrar DateTime campos com base no início do dia, semana, mês, ano atual ou um deslocamento para um desses valores. Por exemplo, você pode encontrar todos os itens criados nos últimos três meses se definir a Field coluna como Created Date, a coluna como Operator, e >= a Value coluna como @StartOfMonth - 3.
@Today Use essa variável para pesquisar itens de trabalho relacionados à data atual ou a uma data anterior. Também é possível modificar a @Today variável subtraindo dias. Por exemplo, você pode encontrar todos os itens ativados na última semana se definir a Field coluna como Activated Date, a coluna como Operator, e >= a Value coluna como @Today - 7.
[Any] Use essa variável para procurar itens de trabalho relacionados a qualquer valor definido para um campo específico.

@me macro

A @me macro substitui o nome da conta integrada do Windows do usuário que executa a consulta. O exemplo a seguir mostra como usar a macro e a instrução estática equivalente. A macro destina-se ao uso com campos de identidade, como Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

@today macro

Você pode usar a @today macro com qualquer DateTime campo. Esta macro substitui a meia-noite da data atual no computador local que executa a consulta. Você também pode especificar @today+x ou @today-y usar deslocamentos inteiros para x dias após @today e y dias antes @today, respectivamente. Uma consulta que usa a @today macro pode retornar diferentes conjuntos de resultados, dependendo do fuso horário em que é executada.

Os exemplos a seguir assumem que hoje é 03/01/2025.

WHERE  
   [System.CreatedDate] = @today

É o equivalente a:

WHERE  
   [System.CreatedDate] = '01-03-2025'

And

WHERE  
   [System.CreatedDate] > @today-2

É o equivalente a:

WHERE  
   [System.CreatedDate] > '01-01-2025'

@StartOfDay, @StartOfWeek, @StartOfMonth, macros @StartOfYear

Você pode usar as @StartOf... macros com qualquer DateTime campo. Esta macro substitui a meia-noite do dia atual, início da semana, início do mês ou início do ano no computador local que executa a consulta.

Essas macros aceitam uma cadeia de caracteres modificadora que tem um formato de (+/-)nn(y|M|w|d|h|m). Semelhante à @Today macro, você pode especificar deslocamentos inteiros para mais ou para menos. Se o qualificador de unidade de tempo for omitido, ele será padronizado para o período natural da função. Por exemplo, @StartOfWeek("+1") é o mesmo que @StartOfWeek("+1w"). Se o sinal de mais/menos (+/-) for omitido, assume-se mais.

Essa sintaxe permite aninhar modificadores e deslocar sua consulta duas vezes. Por exemplo, a cláusula Closed Date >= @StartOfYear - 1 filtra itens de trabalho fechados desde o ano passado. Quando você o modifica para Closed Date >= @StartOfYear('+3M') - 1, ele exclui itens de trabalho fechados nos primeiros três meses do ano passado. A sintaxe WIQL a seguir demonstra:

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

Os exemplos a seguir pressupõem que hoje é 4/5/2025.

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

É o equivalente a:

WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2025'

And

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

É o equivalente a:

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2025'

Macros personalizadas

O WIQL também suporta macros personalizadas arbitrárias. Qualquer cadeia de caracteres prefixada por um @ é tratada como uma macro personalizada e é substituída. O valor de substituição para a macro personalizada é recuperado do parâmetro context do método de consulta no modelo de objeto. O método a seguir é a API usada para macros:

public WorkItemCollection Query(string wiql, IDictionary context)

O parâmetro context contém pares chave-valor para macros. Por exemplo, se o contexto contiver um par chave-valor de (project, ), será MyProject substituído por @project no MyProjectWIQL. Essa substituição é como o construtor de consultas de item de trabalho manipula a @project macro no Visual Studio.

Especificar consultas históricas (ASOF)

Você pode usar uma ASOF cláusula em uma consulta para filtrar itens de trabalho que satisfaçam as condições de filtro especificadas conforme foram definidas em uma data e hora específicas.

Note

Não é possível criar ASOF consultas no construtor de consultas no Visual Studio. Se você criar um arquivo de consulta (.wiq) que inclui uma ASOF cláusula e, em seguida, carregá-lo no Visual Studio, a ASOF cláusula é ignorada.

Suponhamos que um item de trabalho foi classificado em um Iteration Path de e atribuído a 'Jamal Hartnett' antes de Fabrikam Fiber\Release 1 5/05/2025. No entanto, o item de trabalho foi recentemente atribuído a 'Raisa Pokrovskaya' e movido para um novo caminho de iteração da Versão 2. A consulta de exemplo a seguir retorna itens de trabalho atribuídos a Jamal Hartnett porque a consulta é baseada no estado dos itens de trabalho a partir de uma data e hora passadas.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2025 00:00:00.0000000'

Note

Se nenhuma hora for especificada, o WIQL usará meia-noite. Se nenhum fuso horário for especificado, o WIQL usará o fuso horário do computador cliente local.

Definir a ordem de classificação (ORDER BY)

Você pode usar a ORDER BY cláusula para classificar os resultados de uma consulta por um ou mais campos em ordem crescente ou decrescente.

Note

As preferências de classificação do servidor SQL na camada de dados determinam a ordem de classificação padrão. No entanto, você pode usar os asc parâmetros ou desc para escolher uma ordem de classificação explícita.

O exemplo a seguir classifica os itens de trabalho primeiro em Priority ordem crescente (padrão) e, em seguida, Created Date em ordem decrescente (DESC).

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

Para retornar links entre itens de trabalho, especifique FROM WorkItemLinks. As condições de filtro na WHERE cláusula podem se aplicar aos links ou a qualquer item de trabalho que seja a origem ou o destino de um link. O exemplo a seguir retorna os links entre Product Backlog Items e seus itens filho ativos.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
MODE (Recursive)

A tabela a seguir resume as diferenças entre consultas de item de trabalho e consultas de links entre itens de trabalho.

Cláusula Itens de trabalho Ligações entre itens de trabalho
FROM FROM WorkItems FROM WorkItemLinks
WHERE [FieldName] = Value Especifique uma ou mais das seguintes opções:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'
MODE não aplicável Especifique uma das seguintes opções:
- MODE (MustContain): (Padrão) Retorna apenas WorkItemLinkInfo registros em que os critérios de origem, destino e link são todos atendidos.
- MODE (MayContain): Retorna WorkItemLinkInfo registros para todos os itens de trabalho que satisfazem os critérios de origem e link, mesmo que nenhum item de trabalho vinculado satisfaça os critérios de destino.
- MODE (DoesNotContain): Retorna WorkItemLinkInfo registros para todos os itens de trabalho que satisfazem a origem, somente se nenhum item de trabalho vinculado satisfizer os critérios de link e destino.
- MODE (Recursive): Use para consultas de árvore ([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). O tipo de link deve ser topologia de árvore e direção para frente. Retorna WorkItemLinkInfo registros para todos os itens de trabalho que satisfazem a origem, recursivamente para destino. ORDER BY e ASOF não são compatíveis com consultas de árvore.
RETURNS WorkItemQueryResult WorkItemLink

Você pode especificar um dos seguintes nomes de tipo de link do sistema.

Você pode especificar um dos seguintes nomes de tipo de link do sistema ou um tipo de link personalizado definido com o processo XML local.

  • System.LinkTypes.Hierarchy-Forward
  • System.LinkTypes.Related
  • System.LinkTypes.Dependency-Predecessor
  • System.LinkTypes.Dependency-Successor
  • Microsoft.VSTS.Common.Affects-Forward (Processo CMMI)

Para obter mais informações, consulte Referência de tipo de link.

Exemplo de consulta de tipo de árvore

Note

ORDER BY e ASOF não são compatíveis com consultas de árvore. Não inclua essas cláusulas em consultas de árvore.

A consulta a seguir retorna todos os tipos de item de trabalho definidos no projeto atual. O Editor de Consultas exibe a consulta conforme mostrado na imagem a seguir.

Captura de ecrã do Editor de Consultas, consulta em árvore, todos os itens de trabalho e estados.

A sintaxe WIQL equivalente é a seguinte:

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

O exemplo a seguir retorna todos os tipos de item de trabalho definidos no projeto atual. O Editor de Consultas exibe a consulta conforme mostrado na imagem a seguir.

Captura de ecrã do Editor de Consultas, consulta de ligação direta, todos os itens de trabalho e estados.

A sintaxe WIQL equivalente é a seguinte:

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

Mais exemplos de consulta

O exemplo de consulta WIQL típico a seguir usa nomes de referência para os campos. A consulta seleciona itens de trabalho (nenhum tipo de item de trabalho especificado) com um Priority=1arquivo . A consulta retorna o ID e Title do conjunto de retorno como colunas. Os resultados são ordenados por ID ordem crescente.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Padrão de data-hora

Você especifica o padrão de data-hora de acordo com um de dois padrões:

AND [System.ChangedDate] >= '1/1/2025 00:00:00Z'

Cláusulas de exemplo

As instruções de exemplo a seguir mostram cláusulas de qualificação específicas.

Cláusula Example
AND
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND ([System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>OR [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>')
NOT
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
EVER
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
UNDER
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AreaPath] UNDER 'Agile1\Area 0'
ORDER BY
SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ORDER BY [System.Id] [asc | desc]
ASOF (Filtro de tempo)
SELECT [System.Title]<br>FROM workitems<br>WHERE [System.IterationPath] = 'MyProject\Beta'<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ASOF '3/16/25 12:30'

String e texto sem formatação

Literais de cadeia de aspas (aspas simples ou duplas são suportadas) em uma comparação com um String ou PlainText campo. Os literais de cadeia de caracteres suportam todos os caracteres Unicode.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Você pode usar o contains operador para procurar uma substring em qualquer lugar no valor do campo.

WHERE [System.Description] contains 'WIQL'

Área e Iteração (TreePath)

Você pode usar o UNDER operador para os Area Path campos e Iteration Path . O UNDER operador avalia se um valor está dentro da subárvore de um nó de classificação específico. Por exemplo, a expressão a seguir avalia como true se o Area Path were MyProject\Server\Administration, MyProject\Server\Administration\Feature 1, MyProject\Server\Administration\Feature 2\SubFeature 5, ou qualquer outro nó dentro da subárvore.

WHERE [System.AreaPath] UNDER `MyProject\Server\Administration`

Modificadores e operadores especiais

Você pode usar alguns modificadores e operadores especiais em uma expressão de consulta.

Use o IN operador para avaliar se um valor de campo é igual a qualquer um de um conjunto de valores. Este operador é suportado para os Stringtipos , Integer, Doublee DateTime campo. O exemplo a seguir e seu equivalente semântico demonstram isso.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

O EVER operador é usado para avaliar se um valor de campo é igual ou já igualou um determinado valor em todas as revisões anteriores de itens de trabalho. Os Stringtipos , Integer, Doublee DateTime field suportam este operador. Existem sintaxes alternativas para o EVER operador. Por exemplo, os trechos a seguir consultam se todos os itens de trabalho já foram atribuídos a Jamal, Raisa ou Christie.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Use o Copilot para escrever, corrigir e otimizar o WIQL

Você pode usar um assistente de IA (por exemplo, GitHub Copilot ou outros copilotos) para ajudar a criar, corrigir ou otimizar consultas WIQL. Trate o Copilot como uma ajuda à produtividade — não uma fonte autorizada — e sempre revise e teste qualquer consulta gerada antes de executá-la em relação aos dados de produção.

Orientações e melhores práticas:

  • Capacidades: O Copilot pode traduzir requisitos de linguagem simples para WIQL, corrigir erros de sintaxe (colchetes incomparáveis, vírgulas ausentes, palavras-chave incorretas), converter listas SELECT entre nomes amigáveis e de referência, gerar ASOF cláusulas ou literais de data e sugerir regravações de cláusulas para restringir ou ampliar conjuntos de resultados.
  • Validar: sempre valide o WIQL gerado no Editor de Consultas ou em um projeto de teste seguro. Verifique macros (por exemplo @Me, @Today) e formatos de data dependentes de localidade antes de usar.
  • Segurança: Nunca cole segredos, tokens de acesso ou quaisquer cadeias de conexão privadas em prompts. Remova ou retire quaisquer valores confidenciais nos exemplos que você alimenta para o Copilot.
  • Desempenho: Peça ao Copilot para minimizar as cargas úteis dos resultados (retornar apenas os campos necessários), adicionar filtros WHERE apropriados e evitar o uso excessivamente amplo ou IN pesquisas ilimitadas LIKE . Lembre-se do limite de 32 K caracteres para consultas WIQL.
  • Revisar casos de borda: confirme o comportamento de consultas históricas (ASOF), consultas de árvore/link (FROM workItemLinks) e WAS EVER/EVER operadores que verificam revisões — elas podem ser mais complexas e podem precisar de ajuste manual.

Exemplo - Gerar WIQL a partir do inglês simples:

Prompt: "ID de retorno e título para bugs ativos atribuídos no @Me projeto 'Fabrikam' e modificados nos últimos 30 dias. Ordenar por ChangedDate desc."

O copiloto produz:

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

Automatize consultas WIQL com API REST e IA

Você pode usar assistentes de IA, como o Copilot, para automatizar o processo WIQL REST API de duas etapas:

  1. Use a API REST Query By Wiql para recuperar IDs de item de trabalho correspondentes ao seu WIQL.
  2. Use a API Obter Itens de Trabalho para obter detalhes completos para essas IDs.

A IA pode ajudá-lo a:

  • Gere WIQL a partir de linguagem simples e, em seguida, encadeie as duas chamadas de API no código (por exemplo, Python, PowerShell ou JavaScript).
  • Formate e resuma resultados para painéis ou relatórios.

Tip

Para obter detalhes da API REST, consulte Query By Wiql (REST API).

Exemplo: Automatize o WIQL com Python e IA

Suponha que você queira listar os títulos e estados de todos os bugs ativos em um projeto.

Prompt para Copilot:
"Escreva código Python que usa a API REST do Azure DevOps para listar os títulos e estados de todos os bugs ativos no meu projeto. Use o WIQL para obter os IDs e, em seguida, busque os detalhes desses IDs."

Você pode usar o Copilot para gerar um código como este:

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")