在 Azure Boards 中根据日期或当前迭代进行查询

项目
10/21/2024

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

通过本文了解如何根据工作项的创建、关闭、解决或更改时间来列出工作项。可指定日期，或使用支持的宏。使用 @Today 宏并指定相对日期的正负天数。对于根据到团队当前冲刺 (sprint) 的工作项分配列出工作项的查询，请使用 @CurrentIteration。

例如，使用以下查询查找在过去三天内修改的工作项。

显示查询编辑器（显示“更改日期”字段被设为 >= 3）的屏幕截图。

此外，可以使用 CurrentIteration +/- _n_ 宏根据团队迭代的滑动窗口创建查询。

支持的运算符和宏

指定日期时间字段或迭代路径字段的查询子句可以使用下表中列出的运算符和宏。

Data type

支持的运算符和宏

DateTime

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

宏：@StartOfDay、@StartOfWeek、@StartOfMonth、@StartOfYear 和 @Today。可以将 +/- _n_ 与每个受支持的宏一起使用。

TreePath

=、、 <>Under、Not Under
宏：@CurrentIteration¹ 和 @CurrentIteration +/- n² 对迭代路径字段有效。

注意：

Azure DevOps Server 2019.1 及更高版本支持 @StartOfDay、@StartOfWeek、@StartOfMonth 和 @StartOfYear 宏。只有从 Web 门户运行时才支持它们。
Azure DevOps Server 2019 及更高版本支持 @CurrentIteration +/- n 宏。只有从 Web 门户运行时才支持它。

提示

仅当通过 WIQL 语法定义时，WasEver 运算符才可与迭代路径字段一起使用。有关示例，请参阅工作项查询语言 (WIQL) 语法参考。

日期和时间模式

为日期/时间字段输入的日期和时间模式应与通过配置文件选择的日期和时间模式匹配。要查看或更改选择，请参阅设置用户首选项。

显示“时间和区域设置”窗格上的“日期模式”下拉列表选项的屏幕截图。显示“时间和区域设置”窗格上的“时间模式”下拉列表选项的屏幕截图。

显示“时间和区域设置”窗格以及“日期”模式和“时间模式”字段的屏幕截图。

有关使用 @CurrentIteration 宏的客户端限制

可以在以下客户端的查询中使用 @CurrentIteration 宏：

连接到 Azure Boards 的 Web 门户
连接到 Azure Boards 的 Visual Studio 2019 或更高版本
REST API

可以在针对 Azure Boards、Azure DevOps Server 2019 及更高版本的查询中以及使用包含团队作为参数的 REST API 时使用 @CurrentIteration +/- n 宏。示例为 @CurrentIteration('[Project]\Team')。

如果在 Visual Studio 的早期版本中或者从 Microsoft Excel 或 Microsoft Project 中打开包含 @CurrentIteration 宏的查询，则会发生错误。此外，在复制或克隆测试套件和测试用例、定义警报或使用 REST API 时，不能使用宏。

基于日期的查询

按更改日期或特定时间段筛选工作项。限制查询范围。这种方法只返回符合所含日期范围的结果，从而有助于提高性能。如果是创建查询的新手，请参阅定义工作项查询。

并非所有字段对所有工作项类型都有效。跳转到日期字段，了解可以包含在查询中的字段集及其所适用的工作项类型。

提示

请记得在为个人资料设置的日期模式字段中输入日期。
要了解 AND/OR 子句的分组方式，请参阅对子句进行分组。若要查看查询的 WIQL 语法，请安装 WIQL 查询编辑器扩展，以便查看任意查询编辑器条目的 WIQL 版本。

筛选出

包括这些查询子句

过去 30 天内创建的项目。

显示用于查找过去 30 天内创建的项目的查询编辑器子句的屏幕截图。

在特定日期修改的项目。

显示用于查找在特定日期更改的项目的查询编辑器子句的屏幕截图。

今天解决的项目。

显示用于查找今天解决的项目的查询编辑器子句的屏幕截图。

在指定的时间段内关闭的项目。

显示用于查找在指定时间段内关闭的项目的查询编辑器子句的屏幕截图。

未关闭的项目。关闭日期为 null。

显示用于查找“关闭日期”为空或 null 的项目的查询编辑器子句的屏幕截图。

状态在上周更新的项目。

显示状态在上周内更新的项目的查询编辑器子句的屏幕截图。

在当前冲刺期间关闭的项目。宏 <xref href="CurrentIteration" data-throw-if-not-resolved="False" data-raw-source="@CurrentIteration"></xref> 指的是为当前团队上下文定义的冲刺。

显示当前冲刺期间已关闭项目的查询编辑器子句的屏幕截图。

创建基于天、周、月或年开始日期的查询

以下示例演示如何使用 StartOf... 宏来筛选具有各种偏移量的工作项。有关详细信息，请参阅工作项查询语言 (WIQL) 语法。

注意

需要 Azure DevOps Server 2019 Update 1 或更高版本。

筛选目标

包括这些查询子句

过去两周内关闭的 bug。

过去 10 天内修改过的项目。

显示用于查找过去 10 天内更改的项目的查询编辑器子句的屏幕截图。

计划在未来三个月内完成的功能。

显示计划在未来三个月内完成的功能的查询编辑器子句的屏幕截图。

并非所有字段对所有工作项类型都有效。跳转到日期字段，了解可以包含在查询中的字段集及其所适用的工作项类型。

为团队的当前迭代创建查询

如果团队遵循 Scrum 流程，则将工作安排在冲刺 (sprint) 中完成。可使用 @CurrentIteration 宏跟踪要在当前冲刺中完成的要求、bug 和其他工作的进度。有关详细信息，请参阅管理冲刺时间线。

该查询可找到分配给冲刺的任何项目，该项目与团队当前的迭代路径相对应。例如，如果团队在冲刺 (sprint) 5 上，则查询将返回分配给冲刺 (sprint) 5 的项。稍后，当团队在冲刺 (sprint) 6 中工作时，同一查询将返回分配给冲刺 (sprint) 6 的项。

注意

若要使 @CurrentIteration 宏正常工作，团队必须已选择其日期范围包含当前日期的迭代路径。有关详细信息，请参阅选择团队冲刺并设置默认迭代路径。此外，包含此宏的查询仅在从 Web 门户运行时有效。

另请参阅本文前面的 Client restrictions on the use of the @CurrentIteration macros。

选择 @CurrentIteration 或 @CurrentIteration +/- n 宏时，Azure Boards 添加团队参数。团队参数派生自当前团队上下文。

显示使用带团队参数的 CurrentIteration 宏来实现的查询筛选器的屏幕截图。

提示

如果 @CurrentIteration 宏不起作用，请检查是否为团队选择了预期的迭代，以及是否为其设置了日期。有关详细信息，请参阅选择团队冲刺。

要更改系统自动设置的团队参数，可通过在 @CurrentIteration 宏下方添加的参数字段中输入团队名称进行选择。

显示选择团队参数的屏幕截图。

创建团队迭代查询的滑动窗口

想跟踪团队为即将到来的冲刺而规划的工作以及了解以前冲刺中未完成的工作时，请使用 @CurrentIteration +/- n 宏。

注意

若要使 @CurrentIteration +/- n 宏正常工作，团队必须已选择符合 +/- n 条件的迭代路径。日期范围必须包含 @CurrentIteration 的当前日期。有关迭代路径的团队选择的详细信息，请参阅选择团队冲刺并设置默认迭代路径。

另请参阅本文前面的 Client restrictions on the use of the @CurrentIteration macros。

下图显示了如何列出分配给滑动窗口的所有用户故事和 Bug 工作项类型。该窗口跨越了云管理和工具团队选择的最后两个冲刺、当前冲刺和接下来的两个冲刺。

显示 CurrentIteration 加与减子句的屏幕截图。

若要使用此宏，指定的团队必须选择一组跨为此宏输入的 +/- n 值的冲刺。

列出移出冲刺 (sprint) 的工作项

列出为冲刺定义但后来通过使用带子句的查询（其中包含针对迭代路径的 Was Ever 运算符）而移出的工作项。只能使用 WIQL 语法来构造此查询。通过安装 WIQL 编辑器市场扩展，在查询编辑器中编辑 WIQL 语法。

例如，工作项的以下语法查询满足以下条件：

在当前项目中定义。
工作项类型等于“用户故事”或“Bug”。
工作项位于 Fabrikam Fiber Web 团队区域路径下。
工作项未处于Closed、Completed、Cut或Resolved状态。
不在 Fabrikam Fiber Web 团队的当前迭代路径中。
已分配给 Fabrikam Fiber Web 团队的当前迭代路径。
现已分配给 Fabrikam Fiber Web 团队的当前迭代 +1。
已在过去 30 天内更改（冲刺的长度）。

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]

语法的查询编辑器视图如下所示。

注意

查询编辑器会在 Was Ever 运算符旁边显示信息图标，从而表示该子句存在问题。但是，查询仍会运行，你可以创建查询图表。若要修改此查询，则须使用 WIQL 编辑器。

显示从冲刺中移出的查询编辑器工作项的屏幕截图。

列出在开始日期之后添加到冲刺 (sprint) 的工作项

若要列出在开始日期之后新创建且添加到冲刺 (sprint) 的工作项，请使用类似于下图所示的查询。此查询的工作原理是筛选分配给当前冲刺 (sprint) 但在冲刺 (sprint) 开始日期之后创建的工作项。使用 created Date = @Today - 28 子句。

显示查询编辑器工作项在其开始日期后新创建并添加到冲刺中的屏幕截图。

有关查询冲刺范围更改的其他选项，请参阅冲刺范围更改。

“日期”和“迭代路径”字段

使用日期字段筛选查询。当工作项从一种状态变为另一种状态时，其中一些字段填充信息。其中一些字段不会显示在工作项窗体上，但会针对下表中列出的工作项类型跟踪这些字段。

字段名称

说明

工作项类型

激活日期（注释 1 和 2）

创建工作项或将其状态从Closed、Completed或Done状态变为New或Active状态的日期和时间。

引用名称=Microsoft.VSTS.Common.ActivatedDate，数据类型=日期/时间

Bug、变更请求、长篇故事、功能、问题、产品积压工作项、要求、评审、风险、共享步骤、任务、测试用例、用户情景

更改日期

修改工作项时的日期和时间。

引用名称=System.ChangedDate，数据类型=日期/时间

全部

关闭日期（注释 2）

关闭工作项的日期和时间。

引用名称=Microsoft.VSTS.Common.ClosedDate，数据类型=日期/时间

全部

创建日期

创建工作项的日期和时间。

引用名称=System.CreatedDate，数据类型=日期/时间

全部

Due Date

解决问题的预计截止日期。

引用名称=Microsoft.VSTS.Scheduling.DueDate，数据类型=日期/时间

问题 (Agile)

完成日期（注释 3）

日程安排指示任务完成时的日期和时间。

引用名称=Microsoft.VSTS.Scheduling.FinishDate，数据类型=日期/时间

要求、任务、测试计划、用户情景

迭代路径

将工作项按照指定的冲刺 (sprint) 或时间段分组。迭代必须是项目层次结构中的有效节点。为项目定义迭代路径，并为团队选择迭代路径。

引用名称=System.IterationPath，数据类型=TreePath

全部

解决日期（注释 1 和 2）

工作项变为Resolved状态的日期和时间。

引用名称=Microsoft.VSTS.Common.ResolvedDate，数据类型=日期/时间

Bug、变更请求、长篇故事、功能、问题、产品积压工作项、要求、评审、风险、共享步骤、任务、测试用例、用户情景

开始日期（注释 3）

日程安排指示任务开始时的日期和时间。

注意

交付计划使用开始日期和目标日期字段来显示功能、长篇故事和其他项目组合积压工作项的跨度。

引用名称=Microsoft.VSTS.Scheduling.StartDate，数据类型=日期/时间

长篇故事、功能、要求、任务、测试计划、用户情景

状态更改日期

“状态”字段的值更改的日期和时间。

引用名称=Microsoft.VSTS.Common.StateChangeDate，数据类型=日期/时间

全部

目标日期

完成或解决功能、工作项或问题的日期。

注意

交付计划使用开始日期和目标日期字段来显示功能、长篇故事和其他项目组合积压工作项的跨度。

引用名称=Microsoft.VSTS.Scheduling.TargetDate，数据类型=日期/时间

长篇故事、功能

注意：

另请参阅按分配或工作流更改查询。
若要为某一工作项类型定义这些字段，则须将它们包含在此工作项类型定义的 WORKFLOW 部分。例如，在转换为 Resolved 状态时，此语法包含在 FIELDS 定义中。
```
<FIELD refname="Microsoft.VSTS.Common.ResolvedDate" />  
   <SERVERDEFAULT from="clock"  />  
</FIELD >  
```
如果在 Project 中创建项目计划，然后将该计划与存储在 Azure Boards 中的任务同步，则会计算开始日期和完成日期值。这些字段可能不会显示在工作项窗体上，但是会为积压工作项及其链接的任务计算这些字段。你可以从查询的结果或从 Excel 查看它们的只读值。
重要

以下对象不支持 Microsoft Project 集成和 TFSFieldMapping 命令：
- Visual Studio 2019 和 Azure DevOps Office 集成 2019。
- Azure DevOps Server 2019 及更高版本，包括 Azure DevOps Services。
保持对 Microsoft Excel 集成的完全支持，允许批量导入和更新工作项。使用 Microsoft Project 的替代方法包括：
- 交付计划
- 市场扩展，例如 Project Connect 或甘特图

REST API

要以编程方式与查询交互，请参阅以下 REST API 资源之一：

通过

在 Azure Boards 中根据日期或当前迭代进行查询

支持的运算符和宏

日期和时间模式

有关使用 @CurrentIteration 宏的客户端限制

基于日期的查询

创建基于天、周、月或年开始日期的查询

为团队的当前迭代创建查询

创建团队迭代查询的滑动窗口

列出移出冲刺 (sprint) 的工作项

列出在开始日期之后添加到冲刺 (sprint) 的工作项

“日期”和“迭代路径”字段

REST API

反馈

其他资源

通过

在 Azure Boards 中根据日期或当前迭代进行查询

支持的运算符和宏

日期和时间模式

有关使用 @CurrentIteration 宏的客户端限制

基于日期的查询

创建基于天、周、月或年开始日期的查询

为团队的当前迭代创建查询

创建团队迭代查询的滑动窗口

列出移出冲刺 (sprint) 的工作项

列出在开始日期之后添加到冲刺 (sprint) 的工作项

“日期”和“迭代路径”字段

相关文章

REST API

反馈

其他资源