Consulta por data ou iteração atual no Azure Boards

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Neste artigo, saiba como listar itens de trabalho com base em quando eles foram criados, fechados, resolvidos ou alterados. Você pode especificar uma data ou usar uma macro com suporte. Use a macro @Today e especifique um número de dias mais ou menos para datas relativas. Para consultas que listam itens de trabalho com base em sua atribuição ao sprint atual de uma equipe, use @CurrentIteration.

Por exemplo, localize itens de trabalho que foram modificados nos últimos três dias com a seguinte consulta.

Além disso, você pode usar a macro CurrentIteration +/- _n_ para criar consultas com base em uma janela deslizante de iterações de equipe.

Operadores e macros com suporte

Cláusulas de consulta que especificam um campo DateTime ou o campo Caminho da Iteração podem usar os operadores e macros listados na tabela a seguir.

---

Data type

Operadores e macros com suporte

---

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Macros: @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear e @Today. Você pode usar +/- _n_ com cada uma das macros com suporte.

---

TreePath

=, <>, Sob, Não Abaixo
Macros: @CurrentIteration¹ e @CurrentIteration +/- n² válidos com o campo Caminhos de Iteração.

---

Observações:

1. As macros @StartOfDay, @StartOfWeek, @StartOfMonth e @StartOfYear têm suporte do Azure DevOps Server 2019.1 e de versões posteriores. Eles só têm suporte quando são executados no portal da Web.
2. A macro @CurrentIteration +/- n tem suporte do Azure DevOps Server 2019 e de versões posteriores. Só tem suporte quando é executado no portal da Web.

Dica

O operador WasEver pode ser usado com o campo Caminho da Iteração, mas somente quando definido por meio da sintaxe WIQL. Para obter um exemplo, confira Referência de sintaxe WIQL (Work Item Query Language).

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.

Restrições de cliente no uso das macros @CurrentIteration

Você pode usar a macro @CurrentIteration em uma consulta dos seguintes clientes:

• Portal da Web que se conecta ao Azure Boards
• Visual Studio 2019 ou versões posteriores conectadas ao Azure Boards
• A API REST

Você pode usar a macro @CurrentIteration +/- n em uma consulta no Azure Boards, no Azure DevOps Server 2019 e em versões posteriores e com uma API REST que inclui a equipe como um parâmetro. Um exemplo é @CurrentIteration('[Project]\Team').

Ocorrerá um erro se você abrir uma consulta que contenha a macro @CurrentIteration em versões anteriores do Visual Studio ou do Microsoft Excel ou Microsoft Project. Além disso, você não pode usar a macro ao copiar ou clonar conjuntos de testes e casos de teste, definir alertas ou com APIs REST.

Consultas baseadas em data

Filtre os itens de trabalho pela data em que foram alterados ou por um período de tempo específico. Limite o escopo da sua consulta. Essa abordagem pode ajudar no desempenho, retornando apenas resultados que se ajustam ao intervalo de datas incluído. Se você não estiver familiarizado com a criação de consultas, consulte Definir uma consulta de item de trabalho.

Nem todos os campos são válidos para todos os tipos de item de trabalho. Vá para os campos de data para o conjunto de campos que você pode incluir em consultas e os tipos de item de trabalho aos quais eles se aplicam.

Dica

• Lembre-se de inserir datas no campo Padrão de Data definido para seu perfil pessoal.
• Para entender como as cláusulas AND/OR são agrupadas, consulte Cláusulas de grupo. Para exibir a sintaxe WIQL de uma consulta, instale a extensão do editor WIQL, que permite ver a versão WIQL de qualquer entrada do Editor de Consultas.

---

Filtrar por

Incluir estas cláusulas de consulta

---

Itens criados nos últimos 30 dias.

---

Itens modificados em uma data específica.

---

Itens resolvidos hoje.

---

Itens fechados em um período de tempo especificado.

---

Itens que não estão fechados. A data de encerramento é nula.

---

Itens cujos status foram atualizados na última semana.

---

Itens fechados durante o sprint atual. A macro <xref href="CurrentIteration" data-throw-if-not-resolved="False" data-raw-source="@CurrentIteration"></xref> refere-se ao sprint definido para o contexto atual da equipe.

---

Criar consultas baseadas em data de início de dia, semana, mês ou ano

Os exemplos a seguir mostram como usar as macros StartOf... para filtrar itens de trabalho com vários deslocamentos. Para obter mais informações, consulte sintaxe de WIQL (Linguagem de Consulta de Item de Trabalho).

Filtrar por

Incluir estas cláusulas de consulta

---

Bugs fechados nas últimas duas semanas.

---

Itens modificados nos últimos 10 dias.

---

Recursos programados para serem concluídos nos próximos três meses.

---

Nem todos os campos são válidos para todos os tipos de item de trabalho. Vá para os campos de data para o conjunto de campos que você pode incluir em consultas e os tipos de item de trabalho aos quais eles se aplicam.

Criar consultas para a iteração atual da sua equipe

Se a sua equipe seguir os processos do Scrum, você agenda o trabalho a ser concluído em sprints. Você pode acompanhar o progresso dos requisitos, bugs e outros trabalhos a serem concluídos no sprint atual usando a macro @CurrentIteration. Para saber mais, consulte Gerenciar linhas do tempo de sprint.

A consulta encontra qualquer item atribuído a um sprint que corresponda ao caminho de iteração atual da equipe. Por exemplo, se uma equipe estiver no Sprint 5, a consulta retornará itens atribuídos ao Sprint 5. Posteriormente, quando a equipe estiver trabalhando no Sprint 6, a mesma consulta retornará itens atribuídos ao Sprint 6.

Observação

Para que a macro @CurrentIteration funcione, a equipe deve ter selecionado um caminho de iteração cujo intervalo de datas abrange a data atual. Para mais informações, consulte Selecionar sprints de equipe e definir o caminho de iteração padrão. Além disso, as consultas que contêm essa macro só são válidas quando executadas no portal da Web.

Confira também Client restrictions on the use of the @CurrentIteration macros anteriormente neste artigo.

O Azure Boards adiciona um parâmetro de equipe quando você seleciona as macros @CurrentIteration ou @CurrentIteration +/- n. O parâmetro de equipe é derivado do contexto atual da equipe.

Dica

Se a macro @CurrentIteration não estiver funcionando, verifique se a iteração esperada está selecionada para sua equipe e se as datas foram definidas para ela. Para obter mais informações, consulte Selecionar sprints de equipe.

Para alterar o parâmetro de equipe que o sistema define automaticamente, escolha-o inserindo o nome da equipe no campo de parâmetro adicionado abaixo da macro @CurrentIteration.

Criar uma janela deslizante da consulta de iterações da equipe

Use a macro @CurrentIteration +/- n quando quiser acompanhar o trabalho que uma equipe planejou para sprints futuros e para entender o trabalho que não foi concluído em sprints anteriores.

Observação

Para que a macro @CurrentIteration +/- n funcione, a equipe deve ter selecionado caminhos de iteração que atendam aos critérios +/- n. Os intervalos de datas devem abranger a data atual do @CurrentIteration. Para obter mais informações sobre a seleção de equipe de caminhos de iteração, consulte Selecionar sprints de equipe e definir o caminho de iteração padrão.

Confira também Client restrictions on the use of the @CurrentIteration macros anteriormente neste artigo.

A imagem abaixo mostra como listar todos os tipos de item de trabalho História de Usuário e Bug atribuídos à janela deslizante. A janela abrange os dois últimos, o atual e os próximos dois sprints selecionados para a equipe de Administradores e ferramentas da nuvem.

Para usar essa macro, a equipe especificada deve selecionar um conjunto de sprints que abrangem o valor +/- n inserido para a macro.

Listar itens de trabalho removidos de um sprint

Listar itens de trabalho que foram definidos para uma sprint, mas posteriormente removidos usando uma consulta com uma cláusula que contém o operador Was Ever para o campo Caminho de Iteração. Você só pode construir esta consulta usando a sintaxe WIQL. Edite a sintaxe WIQL no Editor de Consultas instalando a Extensão do Editor WIQL do Marketplace.

Por exemplo, as seguintes consultas de sintaxe para itens de trabalho atendem aos seguintes critérios:

• Definido no projeto atual.
• O tipo de item de trabalho é igual a História do Usuário ou Bug.
• Os itens de trabalho estão no Caminho da Área da equipe da Web da Fabrikam Fiber.
• Os itens de trabalho não estão em um estado Closed, Completed, Cut ou Resolved.
• Não no caminho de iteração atual para a equipe da Web da Fabrikam Fiber.
• Foram atribuídos ao caminho de iteração atual para a equipe da Web da Fabrikam Fiber.
• Agora estão atribuídos ao caminho de iteração atual +1 para a equipe da Web da Fabrikam Fiber.
• Foram alterados nos últimos 30 dias (o comprimento do sprint).

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.AssignedTo],
    [System.Title],
    [System.State],
    [System.Tags],
    [System.IterationPath],
    [System.AreaPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] IN ('User Story', 'Bug')
    AND [System.AreaPath] UNDER 'FabrikamFiber\Web'
    AND NOT [System.State] IN ('Completed', 'Closed', 'Cut', 'Resolved')
    AND NOT [System.IterationPath] = @currentIteration('[FabrikamFiber]\Web <id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>')
    AND (
        EVER (
            [System.IterationPath] = @currentIteration('[FabrikamFiber]\Web <id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>')
        )
        AND [System.IterationPath] = @currentIteration('[FabrikamFiber]\Web <id:cdf5e823-1179-4503-9fb1-a45e2c1bc6d4>') + 1
        AND [System.ChangedDate] >= @today - 30
    )
ORDER BY [System.Id]

A exibição Editor de Consultas da sintaxe é exibida conforme mostrado.

Observação

O Editor de Consultas exibe um ícone de informações ao lado do operador Was Ever, indicando um problema com a cláusula. No entanto, a consulta ainda será executada, e você poderá criar gráficos de consulta. Para modificar a consulta, você deve usar o Editor WIQL.

Listar itens de trabalho adicionados a um sprint após a data de início

Para listar os itens de trabalho recém-criados adicionados a um sprint após a data de início, use uma consulta semelhante à mostrada na imagem a seguir. Essa consulta funciona filtrando itens de trabalho atribuídos ao sprint atual, mas foram criados após o início da data de sprint. Use a cláusula created Date = @Today - 28.

Para obter outras opções e consultar alterações no escopo do sprint, consulte Alteração do escopo do sprint.

Campos Data e Caminho de Iteração

Use campos Data para filtrar suas consultas. Alguns desses campos são preenchidos com informações à medida que um item de trabalho progride de um estado para outro. Vários desses campos não aparecem no formulário de item de trabalho, mas são rastreados para esses tipos de item de trabalho listados na tabela a seguir.

Nome do campo

Descrição

Tipos de item de trabalho

---

Data ativada (Observações 1 e 2)

A data e hora em que o item de trabalho foi criado ou quando seu status foi alterado de Closed, Completed ou Done para um estado New ou Active.

Reference name=Microsoft.VSTS.Common.ActivatedDate, Data type=DateTime

Bug, Solicitação de Alteração, Epic, Recurso, Problema, Item de Lista de Pendências do Produto, Requisito, Revisão, Risco, Etapa Compartilhada, Tarefa, Caso de Teste, Histórico do Usuário

Alterar data

A data e a hora em que um item de trabalho foi modificado.

Reference name=System.ChangedDate, Data type=DateTime

Tudo

Data fechada (Observação 2)

A data e a hora em que um item de trabalho foi fechado.

Reference name=Microsoft.VSTS.Common.ClosedDate, Data type=DateTime

Tudo

Data de criação

A data e a hora em que um item de trabalho foi criado.

Reference name=System.CreatedDate, Data type=DateTime

Tudo

Due Date

O prazo previsto para que um problema seja resolvido.

Reference name=Microsoft.VSTS.Scheduling.DueDate, Data type=DateTime

Problema (Agile)

Data de término (Observação 3)

A data e hora em que o agendamento indica que a tarefa estará concluída.

Reference name=Microsoft.VSTS.Scheduling.FinishDate, Data type=DateTime

Requisito, Tarefa, Plano de Teste, História do Usuário

Caminho de Iteração

Agrupa os itens de trabalho por sprints nomeados ou períodos de tempo. A iteração deve ser um nó válido na hierarquia de projetos. Você define caminhos de iteração para um projeto e seleciona caminhos de iteração para uma equipe.

Reference name=System.IterationPath, Data type=TreePath

Tudo

Data Resolvida (Observações 1 e 2)

A data e a hora em que o item de trabalho foi movido para um estado Resolved.

Reference name=Microsoft.VSTS.Common.ResolvedDate, Data type=DateTime

Bug, Solicitação de Alteração, Epic, Recurso, Problema, Item de Lista de Pendências do Produto, Requisito, Revisão, Risco, Etapa Compartilhada, Tarefa, Caso de Teste, Histórico do Usuário

Data de Início (Observação 3)

A data e a hora indicadas no agendamento para o início da tarefa.

Observação

Os Planos de Entrega usam os campos Data de Início e Data de Destino para mostrar o intervalo de recursos, épicos e outros itens de lista de pendências de portfólio.

Reference name=Microsoft.VSTS.Scheduling.StartDate, Data type=DateTime

Épico, Recurso, Requisito, Tarefa, Plano de Teste, História do Usuário

Data da Alteração de Estado

A data e a hora em que o valor do campo Estado foi alterado.

Reference name=Microsoft.VSTS.Common.StateChangeDate, Data type=DateTime

Tudo

Data de Destino

A data pela qual um recurso, item de trabalho ou problema deve ser concluído ou resolvido.

Observação

Os Planos de Entrega usam os campos Data de Início e Data de Destino para mostrar o intervalo de recursos, épicos e outros itens de lista de pendências de portfólio.

Reference name=Microsoft.VSTS.Scheduling.TargetDate, Data type=DateTime

Épico, Recurso

Observações:

1. Consulte também Consulta por atribuição ou alterações de fluxo de trabalho.

2. Para que esses campos sejam definidos para um tipo de item de trabalho, eles devem ser incluídos na seção WORKFLOW da definição de tipo de item de trabalho. Por exemplo, essa sintaxe é incluída na definição FIELDS ao fazer a transição para um estado Resolved.

   <FIELD refname="Microsoft.VSTS.Common.ResolvedDate" />  
      <SERVERDEFAULT from="clock"  />  
   </FIELD >  
   

3. Os valores Data de Início e Data de Término serão calculados se você criar um plano de projeto no Project e sincronizar esse plano com tarefas armazenadas no Azure Boards. Esse campos podem não aparecem no formulário do item de trabalho, mas são calculados para os itens da lista de pendências e tarefas vinculados aos itens da lista de pendências. Você pode exibir seus valores "somente leitura" nos resultados de uma consulta ou do Excel.

   Importante

   A integração do Microsoft Project e o comando TFSFieldMapping não são suportados para:

   • Visual Studio 2019 e Azure DevOps Office Integration 2019.
   • Azure DevOps Server 2019 e versões posteriores, incluindo Azure DevOps Services.

   O suporte completo para a integração do Microsoft Excel é mantido, permitindo a importação e atualização em massa de itens de trabalho. As alternativas para o Microsoft Project incluem:

   • Planos de Entrega
   • Extensões do Marketplace, como o Project Connect ou o gráfico GANTT.

Artigos relacionados

• Consulta por atribuição ou alterações de fluxo de trabalho
• Definir caminhos de iteração (sprint) e configurar iterações de equipe
• Definir uma consulta de item de trabalho no Azure Boards
• Campos, operadores e macros de consulta
• Atributos e campos de item de trabalho
• Sintaxe de WIQL (Work Item Query Language)

API REST

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

• Referência da API REST do Azure DevOps Services
• Consultas
• Linguagem de consulta de item de trabalho
• Buscar itens de trabalho com consultas programaticamente