Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Azure DevOps Services | Servidor Azure DevOps | 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 dá suporte a todas as funções disponíveis por meio do Editor de Consultas do portal da Web, além de mais algumas. Você pode especificar os campos a serem retornados e o agrupamento lógico de cláusulas de consulta. Você também pode usar uma ASOF cláusula para filtrar com base em atribuições a partir de uma data anterior.
Important
A sintaxe WIQL é usada para executar a API REST consulta por Wiql. A API retorna apenas IDs de item de trabalho, independentemente dos campos incluídos na instrução SELECT . Para obter informações completas, (1) obtenha as IDs do WIQL e, em seguida, (2) obtenha os itens de trabalho por meio 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 definido para Permitir. Essas permissões normalmente são concedidas aos membros dos grupos Leitores e Colaboradores de cada projeto de equipe. Para saber mais, confira Permissões e grupos. |
Visão geral da linguagem de consulta
O WIQL tem cinco partes, conforme mostrado no snippet 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 do 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 do Wiql Playground adicionado a Placas.
| 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 períodos. |
FROM |
Indica se você deseja que a consulta localize itens de trabalho ou links entre itens de trabalho. - Use FROM WorkItems para retornar itens de trabalho.- Use FROM workItemLinks para retornar links entre itens de trabalho. Para obter mais informações, consulte Consultas para obter 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 Crescente (Asc) ou Decrescente (Desc) para um ou mais campos. Por exemplo: ORDER BY [State] Asc, [Changed Date] Desc |
ASOF |
Especifica uma consulta histórica, indicando uma data 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 diretrizes fornecidas no Padrão de data e hora.ASOF '02-11-2025' |
Note
As consultas WIQL feitas em placas 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 inserido para campos DateTime deve corresponder ao selecionado em seu perfil. Para exibir ou alterar sua seleção, consulte Definir preferências do usuário.
Aspas (aspas simples ou duplas têm suporte) DateTime literais usados em comparações. Eles devem estar no formato .NET DateTime do computador cliente local executando a consulta. A menos que um fuso horário seja especificado, DateTime 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 dayPrecision parâmetro é igual a false, o tempo é considerado zero (meia-noite). A configuração padrão do dayPrecision parâmetro é false.
Ou você pode especificar o formato ISO 8601, que é válido independentemente da localidade. O ISO 8601 representa a data e a hora começando com o ano, seguido pelo mês, o dia, a hora, os minutos, os segundos e os 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 como usar o 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 o 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 normalmente são rotulados com Custom. o nome anexado e os 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, leia Campos e atributos de item de trabalho.
Especificar cláusulas de filtro (WHERE)
A cláusula WHERE especifica os critérios de filtro. A consulta retorna apenas os itens de trabalho que atendem a os critérios especificados. Por exemplo, o exemplo a seguir de cláusula WHERE retorna as histórias de usuário ativas e 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 fechados, 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 de filtro
Cada condição de filtro é composta por três partes, cada uma das quais deve estar em conformidade com as seguintes regras:
-
Campo: você pode especificar o nome de referência ou o nome amigável. Os seguintes exemplos são uma sintaxe WIQL válida:
- Nome de Referência:
SELECT [System.AssignedTo] ... - Nome amigável com espaços:
SELECT [Assigned To] ... - Nomes sem espaços não exigem colchetes:
SELECT ID, Title ...
- Nome de Referência:
- Operador: os valores válidos são especificados na seção Operadores posteriormente 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,
@Meindica 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 os itens de trabalho que estão atribuídos à pessoa que alterou o item de trabalho recentemente.
Para obter uma descrição e nomes de referência de todos os campos definidos pelo sistema, confira Índice de campo de item de trabalho.
Operators
As consultas usam expressões lógicas para qualificar conjuntos de resultados. Essas expressões lógicas são formadas por uma ou mais operações agrupadas.
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 com suporte para diferentes tipos de campo. Para obter mais informações sobre cada tipo de campo, confira Atributos e campos e atributos de item de trabalho.
Os =operadores , <>, >e <, >=<=como esperado, funcionam conforme o esperado. Por exemplo, System.ID > 100 consultas para todos os itens de trabalho com ID mais de 100.
System.ChangedDate > '01-01-25 12:00:00' consultas para todos os itens de trabalho alteradas após o meio-dia de 1º de janeiro de 2025.
Além desses operadores básicos, há alguns comportamentos e operadores específicos para determinados tipos de campo.
Note
Os operadores disponíveis para você dependem de sua plataforma e versão. Para obter mais informações, confira Consultar referência rápida.
| Tipo de Campo | Operadores suportados |
|---|---|
Boolean |
= , <> , =[Field] , <>[Field] |
DateTime |
= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever |
Double, , GUIDInteger |
= , <> , > , < , >= , <= , =[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 booliano típico para avaliar duas cláusulas. Você pode usar os termos AND EVER e OR EVER ao especificar um operador WAS EVER. Você pode agrupar expressões lógicas e agrupá-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 e under os inoperadores usando not. Não é possível negar o operador ever. O exemplo a seguir consulta todos os itens de trabalho que não são atribuídos sob a subárvore de Fabrikam Fiber\Account Management.
WHERE
[System.TeamProject] = @project
AND [System.WorkItemType] <> ''
AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'
Consulta de exemplo, Nunca Foi Atribuído A
O exemplo do Editor de Consultas a seguir localiza todos os itens de trabalho que foram atribuídos a Jamal Hartnett.
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 pesquisar automaticamente o alias do usuário atual em um campo que contém alias de usuários. Por exemplo, você pode encontrar itens de trabalho que você abriu 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 de equipe selecionado. |
@Project |
Use essa variável para pesquisar itens de trabalho no projeto atual. Por exemplo, você poderá encontrar todos os itens de trabalho no projeto atual se definir a coluna como Field, a Team ProjectOperator coluna como e a = coluna como Value.@Project |
@StartOfDay@StartOfWeek@StartOfMonth@StartOfYear |
Use essas macros para filtrar DateTime campos com base no início do dia atual, semana, mês, ano ou um deslocamento para um desses valores. Por exemplo, você pode encontrar todos os itens criados nos últimos três meses se definir a coluna como Field, a Created Date coluna como Operatore a >= coluna como Value.@StartOfMonth - 3 |
@Today |
Use essa variável para pesquisar itens de trabalho relacionados à data atual ou a uma data anterior. Você também pode modificar a @Today variável subtraindo dias. Por exemplo, você pode encontrar todos os itens ativados na última semana se definir a coluna comoField, a Activated Date coluna como Operator, e a >= coluna como Value.@Today - 7 |
[Any] |
Use essa variável para pesquisar itens de trabalho relacionados a qualquer valor definido para um campo específico. |
Macro @me
A macro @me 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
Macro @today
Você pode usar a @today macro com qualquer DateTime campo. Essa 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 usando deslocamentos inteiros para x dias após @today e y dias antes de @today, respectivamente. Uma consulta que usa a @today macro pode retornar conjuntos de resultados diferentes dependendo do fuso horário em que ela é executada.
Os exemplos a seguir pressupõem que hoje é 3/1/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'
macros @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear
Você pode usar as @StartOf... macros com qualquer DateTime campo. Essa 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 à macro @Today, você pode especificar deslocamentos de mais ou menos inteiros. Se o qualificador de unidade de tempo for omitido, ele usará como padrão o período natural da função. Por exemplo, @StartOfWeek("+1") é o mesmo que @StartOfWeek("+1w"). Se o sinal de mais/menos (+/-) for omitido, será assumido mais.
Essa sintaxe permite aninhar modificadores e deslocar a consulta duas vezes. Por exemplo, a cláusula Closed Date >= @StartOfYear - 1 filtra itens de trabalho fechados desde o ano passado. Ao modificá-lo, Closed Date >= @StartOfYear('+3M') - 1ele exclui itens de trabalho fechados nos três primeiros 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 é 5/04/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 dá suporte a macros personalizadas arbitrárias. Qualquer cadeia de caracteres prefixada por um @ é tratada como macro personalizada e é substituída. O valor de substituição da macro personalizada é recuperado do parâmetro de contexto 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 de contexto contém pares chave-valor para macros. Por exemplo, se o contexto contiver um par chave-valor de (project, ), então MyProject será substituído pelo @projectMyProjectWIQL. Essa substituição é como o construtor de consultas de item de trabalho lida com a @project macro no Visual Studio.
Especificar consultas históricas (ASOF)
Você pode usar uma cláusula ASOF 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
Você não pode criar consultas ASOF no construtor de consultas do Visual Studio. Se você criar um arquivo de consulta (.wiq) que inclua uma ASOF cláusula e, em seguida, carregá-lo no Visual Studio, a ASOF cláusula será ignorada.
Suponha que um item de trabalho tenha sido classificado em um Iteration Path de Fabrikam Fiber\Release 1 e atribuído a 'Jamal Hartnett' antes de 05/05/2025. No entanto, o item de trabalho foi recentemente atribuído a "Raisa Pokrovskaya" e movido para um novo caminho de iteração do Lançamento 2. A consulta de exemplo a seguir retorna itens de trabalho atribuídos a Jamal Hartnett, pois 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 cláusula ORDER BY 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 SQL Server na camada de dados determinam a ordem de classificação padrão. No entanto, você pode usar os parâmetros asc ou desc para escolher uma ordem de classificação explícita.
O exemplo a seguir classifica os itens de trabalho primeiro por Priority ordem crescente (padrão) e, em seguida, em Created Date 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
Consultar por links entre os itens de trabalho
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 | Links entre itens de trabalho |
|---|---|---|
FROM |
FROM WorkItems |
FROM WorkItemLinks |
WHERE |
[FieldName] = Value |
Especifique um ou mais dos seguintes:[Source].[FieldName] = Value[Target].[FieldName] = Value[System.Links.LinkType] = 'LinkName' |
MODE |
não aplicável | Especifique um dos seguintes: - MODE (MustContain): (Padrão) Retorna apenas WorkItemLinkInfo registros em que os critérios de origem, destino e link estão todos satisfeitos.- MODE (MayContain): retorna WorkItemLinkInfo registros para todos os itens de trabalho que atendem aos critérios de origem e link, mesmo que nenhum item de trabalho vinculado atenda aos critérios de destino.- MODE (DoesNotContain): retorna WorkItemLinkInfo registros para todos os itens de trabalho que atendem à origem, somente se nenhum item de trabalho vinculado atender aos critérios de link e de 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 atendem à origem, recursivamente para o 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-ForwardSystem.LinkTypes.RelatedSystem.LinkTypes.Dependency-PredecessorSystem.LinkTypes.Dependency-Successor-
Microsoft.VSTS.Common.Affects-Forward(processo CMMI)
Para obter mais informações, confira Referência do 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.
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)
Exemplo de consulta de link direto
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.
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 consultas
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=1. A consulta retorna o ID e Title do conjunto de retorno como colunas. Os resultados são classificados 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
Especifique o padrão de data/hora de acordo com um dos dois padrões:
- O formato Padrão de Data e Padrão de Hora vem de suas preferências de usuário, hora e localidade
- O padrão especificado por UTC, que segue esse padrão (com Z acrescentado à data e hora).
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' |
Cadeia de caracteres e PlainText
Literais de cadeia de caracteres de aspas (aspas simples ou duplas têm suporte) em uma comparação com um String ou PlainText um campo. Literais de cadeia de caracteres dão suporte a todos os caracteres Unicode.
WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'
Você pode usar o contains operador para pesquisar uma subcadeia de caracteres em qualquer lugar no valor do campo.
WHERE [System.Description] contains 'WIQL'
Área e Iteração (TreePath)
Você pode usar o UNDER operador para o e Area Path camposIteration Path. O operador UNDER avalia se um valor está dentro da subárvore de um nó de classificação específico. Por exemplo, a expressão a seguir será avaliada como true se forem Area PathMyProject\Server\Administration, MyProject\Server\Administration\Feature 1ou MyProject\Server\Administration\Feature 2\SubFeature 5qualquer 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 operador IN para avaliar se um valor de campo é igual a qualquer um de um conjunto de valores. Esse operador tem suporte para os Stringtipos de campo, , IntegerDoublee DateTime . 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 igual a um valor específico em todas as revisões passadas de itens de trabalho. Os Stringtipos de campo, , IntegerDoublee , dão DateTime suporte a esse operador. Há sintaxes alternativas para o operador EVER. Por exemplo, os snippets 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>'
)
Usar o Copilot para gravar, corrigir e otimizar o WIQL
Você pode usar um assistente de IA (por exemplo, GitHub Copilot ou outros copilots) para ajudar a criar, corrigir ou otimizar consultas WIQL. Trate o Copilot como um auxílio de produtividade, não uma fonte autoritativa, e sempre examine e teste qualquer consulta gerada antes de executá-la em relação aos dados de produção.
Diretrizes e práticas recomendadas:
-
Funcionalidades: o Copilot pode converter requisitos de linguagem simples em WIQL, corrigir erros de sintaxe (colchetes incompatíveis, vírgulas ausentes, palavras-chave incorretas), converter listas SELECT entre nomes amigáveis e de referência, gerar
ASOFcláusulas ou literais de data e sugerir regravações de cláusula para restringir ou ampliar conjuntos de resultados. -
Validar: sempre valide o WIQL gerado no Editor de Consultas ou um projeto de teste seguro. Verifique as macros (por exemplo
@Me,@Today) e os formatos de data dependentes da localidade antes do uso. - Segurança: nunca cole segredos, tokens de acesso ou cadeias de conexão privadas em prompts. Remova ou redigir quaisquer valores confidenciais nos exemplos que você alimenta para Copilot.
-
Desempenho: peça ao Copilot para minimizar os conteúdos de resultados (retornar somente os campos necessários), adicionar filtros WHERE apropriados e evitar o uso excessivamente amplo de
INpesquisas ou não associadosLIKE. Lembre-se do limite de caracteres de 32 K para consultas WIQL. -
Examinar casos de borda: confirme o comportamento de consultas históricas (
ASOF), consultas de árvore/link (FROM workItemLinks) eWAS EVER/EVERoperadores que verificam revisões— elas podem ser mais complexas e podem precisar de ajuste manual.
Exemplo – Gerar WIQL em inglês sem formatação:
Prompt: "ID de retorno e título para bugs ativos atribuídos no @Me projeto 'Fabrikam' e modificados nos últimos 30 dias. Classificar por ChangedDate desc."
Copilot 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
Automatizar consultas WIQL com API REST e IA
Você pode usar assistentes de IA, como o Copilot, para automatizar o processo de API REST WIQL de duas etapas:
- Use a API REST consulta por Wiql para recuperar IDs de item de trabalho correspondentes ao WIQL.
- Use a API Obter Itens de Trabalho para buscar detalhes completos para essas IDs.
A IA pode ajudá-lo:
- Gere WIQL de linguagem simples e encadee as duas chamadas à API no código (por exemplo, Python, PowerShell ou JavaScript).
- Formatar e resumir resultados para dashboards ou relatórios.
Tip
Para obter detalhes da API REST, consulte Consulta por Wiql (API REST).
Exemplo: Automatizar 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 o código Python que usa a API REST do Azure DevOps para listar os títulos e estados de todos os bugs ativos em meu projeto. Use WIQL para obter as IDs e, em seguida, buscar os detalhes dessas IDs."
Você pode usar 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.")