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

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
マクロ: @CurrentIteration1@CurrentIteration +/- n2反復パスフィールドで有効です。


注:

  1. @StartOfDay@StartOfWeek@StartOfMonth および @StartOfYear マクロは、Azure DevOps Server 2019.1 以降のバージョンでサポートされており、Web ポータルから実行する場合にのみ有効です。
  2. @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を使用するときも、このマクロは使用できません。

日付ベースのクエリ

作業項目を変更した日付または特定の期間ごとにフィルタリングします。 クエリーの範囲を制限します。これは、含まれる日付範囲に合った結果だけを返すことで、パフォーマンスに役立ちます。 初めてクエリを作成する場合は、「クエリ エディターを使用してクエリを一覧表示し、管理する」を参照してください。

すべてのフィールドがすべての作業項目の種類に対して有効なわけではありません。 クエリに含めることができるフィールドの一致機に対する [日付] フィールドと適用する作業項目の種類に移動します。

ヒント


フィルターの対象

含めるクエリ句


過去 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 週間でクローズされたバグ。

過去 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 マクロを使用したクエリ フィルターを示すスクリーンショット。

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

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

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

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

メモ

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

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

次の画像では、Cloud Admin と Tools チームに対して選択された、直近の 2 つのスプリント、現在のスプリントおよび次の 2 つのスプリントを網羅する [スライディング] ウィンドウに割り当てられる すべての User Story および Bug 作業項目の一覧方法を示しています。

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

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

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

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

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

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

作業項目が作成された、またはその状態が ClosedCompletedDone から 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

エピック、機能

メモ:

  1. 「割り当てまたはワークフローの変更によるクエリの実行」の「日付フィールドと ID フィールド」も参照してください。

  2. 作業項目の種類に対して定義するこれらのフィールドは、WORKFLOW作業項目の種類定義のセクションに含める必要があります。 たとえば、この構文は、Resolved 状態に変更する際に FIELDS 定義内に含まれます。

     <FIELD refname="Microsoft.VSTS.Common.ResolvedDate" />  
        <SERVERDEFAULT from="clock"  />  
     </FIELD >  
    
  3. 開始日終了日 の値は、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 を使用する代わりに、次のような方法があります。

REST API

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