Azure Boards で日付または現在のイテレーションによるクエリを実行する

[アーティクル]
10/15/2024

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

この記事では、作業項目が作成、終了、解決、または変更された日時に基づいて作業項目を一覧表示する方法について説明します。日付を指定することも、サポートされているマクロを使用することもできます。 @Today マクロを使用し、基準日に対して加算または減算する日数を指定します。チームの現在のスプリントへの割り当てに基づいて作業項目を一覧表示するクエリでは、@CurrentIteration を使用します。

たとえば、次のクエリーを使用して、過去 3 日間に変更された作業項目を検索します。

[変更日] フィールドが >= 3 に設定されているクエリエディターを示すスクリーンショット。

また、CurrentIteration +/- _n_ マクロを使用して、チームイテレーションのスライディングウィンドウに基づいてクエリを作成することもできます。

サポートされている演算子とマクロ

[DateTime] フィールドまたは [イテレーションパス] フィールドを指定するクエリ句では、次の表に示す演算子とマクロを使用できます。

データの種類

サポートされている演算子とマクロ

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²は反復パスフィールドで有効です。

注:

@StartOfDay、@StartOfWeek、@StartOfMonth および @StartOfYear マクロは、Azure DevOps Server 2019.1 以降のバージョンでサポートされています。これらは、Web ポータルから実行する場合にのみサポートされます。
@CurrentIteration +/- n マクロは、Azure DevOps Server 2019 以降のバージョンでサポートされています。これらは、Web ポータルから実行する場合にのみサポートされます。

ヒント

WasEver 演算子は、WIQL 構文で定義されている場合のみ、[イテレーションパス] フィールドで使用できます。例については、「作業項目クエリ言語 (WIQL) 構文リファレンス」を参照してください。

日付と時刻のパターン

DateTime フィールドに入力する日付と時間のパターンは、プロファイルで選んだものと一致する必要があります。選んだ内容を確認または変更するには、「ユーザーの優先設定を設定する」を参照してください。

[時刻とロケール] ペインの [日付パターン] ドロップダウンオプションを示すスクリーンショット。 [時刻とロケール] ペインの [時刻パターン] ドロップダウンオプションを示すスクリーンショット。

[日付パターン] フィールドと [時刻パターン] フィールドを含む [時刻とロケール] ペインを示すスクリーンショット。

@CurrentIteration マクロの使用に関するクライアントの制限

クエリで @CurrentIteration マクロを使用できるのは次のクライアントです。

Azure Boards に接続する Web ポータル
Azure Boards に接続されている Visual Studio 2019 以降のバージョン
REST API

Azure Boards, Azure DevOps Server 2019 以降のバージョンに対するクエリにある @CurrentIteration +/- n マクロを使用します。これには、パラメーターとしてチームを含む REST API があります。たとえば @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 以降のバージョンが必要です。

フィルターの対象

含めるクエリ句

過去 2 週間でクローズされたバグ。

過去 10 日間で修正された項目。

過去 10 日間で変更された項目を検索するためのクエリエディター句を示すスクリーンショット。

今後 3 か月以内に完了する予定の機能。

今後 3 か月で完了する予定の機能のクエリエディター句を示すスクリーンショット。

チームの現在のイテレーションのクエリを作成する

チームがスクラムプロセスに従っている場合は、作業がスプリント単位で完了するようにスケジュールします。 @CurrentIteration マクロを使用して、現在のスプリントで完了する要件、バグ、およびその他の作業の進捗を追跡できます。詳細については、「スプリントタイムラインを管理する」を参照してください。

クエリは、チームの現在のイテレーションパスに対応するスプリントに割り当てられた項目を検索します。たとえば、チームがスプリント 5 に対応している場合は、スプリント 5 に割り当てられた項目がクエリによって返されます。その後、チームがスプリント 6 で作業しているときは、同じクエリによって、スプリント 6 に割り当てられた項目が返されます。

メモ

@CurrentIteration マクロを機能させるには、チームが現在の日付を含む日付範囲のイテレーションパスを選択している必要があります。詳細については、「チームスプリントを選択してデフォルトのイテレーションパスを設定する」を参照してください。また、このマクロを含むクエリは、Web ポータルから実行する場合にのみ有効です。

この記事で前述されている「Client restrictions on the use of the @CurrentIteration macros」も参照してください。

@CurrentIteration または @CurrentIteration +/- n マクロを選択すると、Azure Boards によってチームパラメーターが追加されます。 Team パラメーターは、現在のチームコンテキストから派生します。

Team パラメーターで CurrentIteration マクロを使用したクエリフィルターを示すスクリーンショット。

ヒント

@CurrentIteration マクロが機能しない場合は、チームに対して想定されるイテレーションが選択されていること、および日付が設定されていることを確認します。詳細については、「チームスプリントを選択する」を参照してください。

システムで自動的に設定されチームパラメーターを変更するには、@CurrentIteration マクロの下に追加される [パラメータ] フィールドにチームの名前を入力して選択します。

Team パラメーターの選択を示すスクリーンショット。

チームのイテレーションクエリのスライディングウィンドウを作成する

@CurrentIteration +/- n マクロは、今後のスプリントに向けてチームが計画していた作業を追跡する場合や、以前のスプリントでは完了していなかった作業を理解する場合に使用します。

メモ

@CurrentIteration +/- n マクロを機能させるには、チームが +/- n 条件を満たすイテレーションパスを選択している必要があります。日付範囲は、@CurrentIteration の現在の日付を含む必要があります。イテレーションパスのチーム選択に関する詳細については、「チームスプリントを選択してデフォルトのイテレーションパスを設定する」を参照してください。

この記事で前述されている「Client restrictions on the use of the @CurrentIteration macros」も参照してください。

次の図は、スライディングウィンドウに割り当てられているすべてのユーザーストーリーとバグの作業項目の種類を一覧表示する方法を示しています。このウィンドウは、クラウド管理チームとツールチーム用に選択された最後の 2 つのスプリント、現在のスプリント、および次の 2 つのスプリントにまたがっています。

CurrentIteration のプラス句とマイナス句を示すスクリーンショット。

このマクロを使用するには、指定したチームが、マクロに入力された +/- n 値を網羅するスプリントセットを選択する必要があります。

スプリントから移された作業項目を一覧表示する

スプリントに定義されたが、[イテレーションパス] の Was Ever 演算子を含む句を含むクエリを使用して後で移動した差表項目を一覧します。このクエリは、WIQL 構文を使用しないと作成できません。 WIQL エディタマーケットプレース拡張機能をインストールすることで、クエリーエディタで WIQL 構文を編集します。

たとえば、作業項目に関する次の構文クエリーは、次の基準を満たしています。

現在のプロジェクトで定義されています。
作業項目の種類が User Story または Bug と等しい。
作業項目は、Fabrikam Fiber Web チームの Area Path の下にあります。
作業項目が、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 エディタを使用する必要があります。

クエリエディターの作業項目がスプリントから移動されたことを示すスクリーンショット。

開始日の後にスプリントに追加された作業項目を一覧表示する

スプリント開始日の後に新たに作成されてスプリントに追加された作業項目を一覧表示するには、次の図のようなクエリを使用します。このクエリは、現在のスプリントに割り当てられているがスプリントの開始日より後に作成された作業項目をフィルター処理することで機能します。 created Date = @Today - 28 句を使用します。

クエリエディターの作業項目が新しく作成され、開始日後にスプリントに追加されることを示すスクリーンショット。

スプリントスコープの変更をクエリするためのその他のオプションについては、「スプリントスコープの変更」を参照してください。

日付およびイテレーションパスのフィールド

クエリーをフィルタ処理するには、[日付] フィールドを使用します。これらのフィールドの一部では、作業項目がある状態から別の状態に進むにつれて情報が設定されます。これらのフィールドのいくつかは作業項目フォームには表示されませんが、次の表に示す作業項目の種類に関して追跡されます。

フィールド名

説明

作業項目の種類

アクティブ化された日付 (注 1 および 2)

作業項目が作成された、またはその状態が Closed、Completed、Done から New または Active 状態に変更された日時。

参照名=Microsoft.VSTS.Common.ActivatedDate、データ型=DateTime

バグ、変更要求、エピック、機能、懸案事項、プロダクトバックログ項目、要件、レビュー、リスク、共有ステップ、タスク、テストケース、ユーザーストーリー

変更日

作業項目が変更された日時。

参照名=System.ChangedDate、データ型=DateTime

すべて

終了日 (注 2)

作業項目が終了した日時。

参照名=Microsoft.VSTS.Common.ClosedDate、データ型=DateTime

すべて

作成日

作業項目が作成された日時。

参照名=System.CreatedDate、データ型=DateTime

すべて

Due Date

懸案事項の解決の予想される期限。

参照名=Microsoft.VSTS.Scheduling.DueDate、データ型=DateTime

懸案事項 (アジャイル)

完了日 (注 3)

スケジュールに示されているタスクの完了日時。

参照名=Microsoft.VSTS.Scheduling.FinishDate、データ型=DateTime

要件、タスク、テスト計画、ユーザーストーリー

イテレーションパス

名前付きスプリントまたは期間により作業項目を分類します。このイテレーションは、プロジェクト階層で有効なノードである必要があります。プロジェクトのイテレーションパスを定義し、チームのイテレーションパスを選択します。

参照名=System.IterationPath、データ型=TreePath

すべて

解決日 (注 1 および 2)

作業項目が Resolved 状態に変更された日時。

参照名=Microsoft.VSTS.Common.ResolvedDate、データ型=DateTime

開始日 (注 3)

スケジュールに示されているタスクの開始日時。

メモ

配信計画は、[開始日] と [対象日] フィールドを使用して、機能の範囲、エピック、およびその他ポートフォリオバックログ項目を表示します。

参照名=Microsoft.VSTS.Scheduling.StartDate、データ型=DateTime

エピック、機能、要件、タスク、テスト計画、ユーザーストーリー

状態の変更日

State フィールドの値が変更された日時。

参照名=Microsoft.VSTS.Common.StateChangeDate、データ型=DateTime

すべて

目標とする日

機能、作業項目、または懸案事項が完了すなわち解決される日付。

メモ

参照名=Microsoft.VSTS.Scheduling.TargetDate、データ型=DateTime

エピック、機能

メモ:

また、「割り当てまたはワークフロー変更によるクエリ」も参照してください。
作業項目の種類に対して定義するこれらのフィールドは、WORKFLOW作業項目の種類定義のセクションに含める必要があります。たとえば、この構文は、Resolved 状態に変更する際に FIELDS 定義内に含まれます。
```
<FIELD refname="Microsoft.VSTS.Common.ResolvedDate" />  
   <SERVERDEFAULT from="clock"  />  
</FIELD >  
```
開始日 と 終了日 の値は、Projectでプロジェクト計画を作成し、その計画を Azure Boards に格納されているタスクと同期する場合に計算されます。これらのフィールドは、作業項目で表示されない場合がありますが、バックログ項目バックログ項目にリンクされているとタスクに対しては計算されます。読み取り専用の値は、クエリまたは Excel からの結果で表示されます。
重要

Microsoft Project Integration および TFSFieldMapping コマンドは、以下ではサポートされていません。
- Visual Studio 2019 および Azure DevOps Office Integration 2019。
- Azure DevOps Server 2019 以降のバージョン (Azure DevOps Services を含む)。
Microsoft Excel 統合の完全なサポートが維持されるため、作業項目の一括インポートと更新が可能です。 Microsoft Project を使用する代わりに、次のような方法があります。
- 配信計画
- Project Connect や GANTT チャートなどの Marketplace 拡張機能

REST API

プログラムでクエリを操作するには、次の REST API リソースのいずれかを参照してください。

次の方法で共有

Azure Boards で日付または現在のイテレーションによるクエリを実行する

サポートされている演算子とマクロ

日付と時刻のパターン

@CurrentIteration マクロの使用に関するクライアントの制限

日付ベースのクエリ

開始日、週の開始日、月の開始日、または年の開始日に基づいたクエリを作成する

チームの現在のイテレーションのクエリを作成する

チームのイテレーションクエリのスライディングウィンドウを作成する

スプリントから移された作業項目を一覧表示する

開始日の後にスプリントに追加された作業項目を一覧表示する

日付およびイテレーションパスのフィールド

REST API

フィードバック

その他のリソース

次の方法で共有

Azure Boards で日付または現在のイテレーションによるクエリを実行する

サポートされている演算子とマクロ

日付と時刻のパターン

@CurrentIteration マクロの使用に関するクライアントの制限

日付ベースのクエリ

開始日、週の開始日、月の開始日、または年の開始日に基づいたクエリを作成する

チームの現在のイテレーションのクエリを作成する

チームのイテレーション クエリのスライディング ウィンドウを作成する

スプリントから移された作業項目を一覧表示する

開始日の後にスプリントに追加された作業項目を一覧表示する

日付およびイテレーション パスのフィールド

関連記事

REST API

フィードバック

その他のリソース

チームのイテレーションクエリのスライディングウィンドウを作成する

日付およびイテレーションパスのフィールド