Azure Boards で作業項目クエリを定義する

  • [アーティクル]

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

Visual Studio 2019 | Visual Studio 2022

作業項目クエリでは、指定したフィルター条件に基づいて作業項目のリストが生成されます。 これらのマネージド クエリを保存して他のユーザーと共有できます。

クエリは、Web ポータルまたはサポートされているクライアント (Visual Studio チーム エクスプローラーなど) から作成できます。 一括更新や追加をサポートするには、Excel または .csv ファイルを使用してクエリをインポートまたはエクスポートします。

この記事の後半の推奨されるベスト プラクティスを確認してください。

前提条件

  • 共有クエリを表示して実行するには、利害関係者アクセス権が必要です。 既定では、すべてのプロジェクト メンバーに利害関係者アクセス権があります。 詳細については、共有クエリまたはフォルダーのアクセス許可の変更に関するページ参照してください。
  • 共有クエリを追加して保存するには、Basic 以上のアクセス権が必要です。
  • クエリを追加するフォルダーに対する投稿アクセス許可が [許可] に設定されている必要があります。 既定では、共同作成者グループにはこのアクセス許可が ''ありません''。

注意

パブリック プロジェクトの利害関係者アクセスが付与されたユーザーは、基本アクセスが付与されたユーザーと同様に、クエリ機能へのフル アクセス権を持っています。 詳細については、「利害関係者アクセスクイック リファレンス」を参照してください。

  • 既定では、利害関係者アクセスが付与されたすべてのプロジェクト メンバーとユーザーが、すべての共有クエリを表示して実行することができます。 共有クエリ フォルダーまたは共有クエリに設定されているアクセス許可は変更することができます。 詳細については、「クエリのアクセス許可を設定する」を参照してください。
  • [共有クエリ] でクエリを追加して保存するには、基本以上のアクセス権が付与されている必要があります。 また、クエリを追加するフォルダーに対する投稿アクセス許可が [許可] に設定されている必要があります。 既定では、共同作成者グループにはこのアクセス許可がありません。

クエリ フィルターを選択する

クエリ エディターから、フィルターを選択して、サンプル クエリを含む記事にジャンプできます。 クエリ フィルターに加えて、クエリ結果にフィルターを対話的に適用できます。

注意

マネージド クエリでは近接検索はサポートされていませんが、セマンティック検索ではサポートされます。 さらに、セマンティック検索では * と ? の両方がワイルドカード文字としてサポートされており、複数のワイルドカード文字を使用して複数の文字を照合できます。 詳細については、「機能作業項目の検索」を参照してください。

フィルター処理機能

マクロ

Filter 関数を使用して、クエリを対話的にフィルター処理することもできます。

クエリを開く

Web ブラウザーから、(1) 正しいプロジェクトが選択されていることを確認し、(2) [Boards] > [クエリ] を選んでから、(3) [すべて] を選択します。

[Boards] > [クエリ] を開く、縦型ナビゲーション

[クエリ] を開くのが初めての場合は、ページに [お気に入り] が表示されます。 このページには、お気に入りとして指定したクエリの一覧が表示されます。 それ以外の場合は、[すべて] を選択して、ユーザーが定義したすべてのクエリと、プロジェクトに対して定義された共有クエリを表示できます。

ヒント

[お気に入り] ページには、ユーザーまたはチームがお気に入りとして選択したクエリが表示されます。 [プロジェクト] ページには、お気に入りのクエリと共に他のオブジェクトも表示されます。 詳細については、「個人またはチームのお気に入りを設定する」を参照してください。

フラット リスト クエリを定義する

新しいクエリは、Web ポータルの [クエリ] タブまたはチーム エクスプローラーの [作業項目] タブから開始します。

[新しいクエリ] を選択します。

新しいクエリの追加のスクリーンショット (新しいエクスペリエンス)。

クエリ エディターには、次の既定の設定が表示されます: [作業項目の単純なリスト]、[作業項目の種類]=[Any]、および [状態]=[Any]。

作業項目のフラット リストが選択されているクエリ エディターのスクリーンショット。

[値] を変更し、句を追加または削除するか、[クエリの種類] を [作業項目とダイレクト リンク] または [作業項目のツリー] に変更します。

プロジェクト間またはプロジェクト内でクエリを実行する

新しいクエリは、既定では、現在のプロジェクトにスコープが設定されています。 しかし、組織またはプロジェクト コレクション内で定義されている作業項目を検索するクエリを作成できます。 しかし、保存したすべてのクエリは、特定のプロジェクトに保存されます。

2 つ以上のプロジェクトで定義されている作業項目を一覧表示するには、[複数プロジェクトに対するクエリ] をオンにします。 たとえば、次のクエリでは、過去 30 日以内のすべてのプロジェクトで作成されたすべての機能が検索されます。

複数プロジェクトに対するクエリがオンになっているクエリ エディターのスクリーンショット。

[複数プロジェクトに対するクエリ] をオンにすると、[チーム プロジェクト] フィールドを追加して、選択した数のプロジェクトで絞り込みを行うことができます。

クエリ エディターのスクリーンショット。チーム プロジェクトとその他のフィールドがフィルター処理に追加されています。

Note

複数のプロジェクト名を区切るには、クライアント コンピューターに定義されている地域設定に対応するリスト区切り記号 (たとえば、コンマ ,) を使用します。

  • [チーム プロジェクト] フィールドは、[複数プロジェクトに対するクエリ] をオンにした後でのみ使用できます。
  • [複数プロジェクトに対するクエリ] がオンの場合は、コレクション内のすべてのプロジェクトで定義されているすべての種類の作業項目から、すべてのフィールドが [フィールド] ドロップダウン メニューに表示されます。
  • [複数プロジェクトに対するクエリ] がオフになっている場合は、現在のプロジェクトで定義されている作業項目の種類のフィールドのみが [フィールド] ドロップダウン メニューに表示されます。

句を定義する

クエリを作成するには、1 つまたは複数の句を定義します。 各句では、1 つのフィールドのフィルター条件を定義します。

サンプルのクエリ句

[ルールの適用条件] フィールド 演算子 値
And 割当先 = @Me

フィールド データ型に基づく使用可能な演算子の一覧については、クエリ インデックスのクイック リファレンスに関する記事を参照してください。

すべての句は、And ステートメントとして追加されます。 グループ化を変更するには、[Or] を選択します。 句のステートメントが必要なシーケンスで確実に実行されるように、句をグループ化します。

[新しい句の追加] を選択して、クエリの最後に別の句を追加し、その句の [フィールド]、[演算子]、[値] を選びます。

句の追加方法を示すクエリ エディターのスクリーンショット。

たとえば、自分に割り当てられているすべての作業項目を検索するには、[担当者] フィールド、等号 (=) 演算子、および自分のユーザー ID を表す @Me マクロを指定します。

ヒント

クエリの WIQL 構文と、かっこを使用して句をグループ化する方法を表示するには、Marketplace Wiql エディターをインストールします。 この拡張機能では、WIQL 構文を表示し、それを WIQL ファイルにエクスポートして REST API 呼び出しで使用することができます。 詳細については、「作業項目クエリ言語 (WIQL) の構文」を参照してください。

クエリ句を定義するためのチェックリスト

  1. 最初の空白行の [フィールド] 列見出しで、下向きの矢印をクリックして使用できるフィールドを表示し、一覧から項目をクリックします。 詳細については、「クエリ フィールドと値」を参照してください。

  2. 同じ行の [演算子] 列見出しで、下向きの矢印を選択して使用できる演算子のリストを表示し、リストで項目を選びます。 詳細については、「演算子」を参照してください。

  3. 同じ行の [値] 列見出しで、値を入力するか、下向きの矢印を選択し、リストで項目を選びます。 マクロまたは変数を使用して現在のプロジェクト、ユーザー、日付、またはその他の選択項目を指定する方法の詳細については、「変数」を参照してください。

  4. 句を追加するには、[新しい句の追加] 選択します。

    クエリの末尾に句を追加することも、対応するアイコンを使用して次のタスクを実行することもできます。

    • 新しいフィルター行を挿入
    • フィルター行を削除
    • 選択した句のグループ化
    • 句のグループ解除

作業項目ツリーを使用して階層を表示する

[作業項目のツリー] クエリを使用して、作業項目のリストを入れ子になった多層のリストとして表示できます。 たとえば、すべてのバックログ項目と、それらにリンクされたタスクを表示できます。 ツリーのさまざまな部分に注目するには、[すべて展開] または [すべて折りたたむ] を選択します。

注意

Test Plans、テスト スイート、テスト ケースの階層ビューを表示するクエリを構築することはできません。 これらの項目は、親子リンクの種類を使って一緒にリンクされません。 ただし、テスト関連の作業項目を一覧表示するダイレクト リンク クエリを作成することはできます。 また、[Test Plans] ページを使用して階層を表示することもできます。

ツリー クエリを示すクエリ結果一覧のスクリーンショット。

親と子の両方の作業項目に対してフィルター条件を定義します。 リンクされた子を検索するには、[最上位の作業項目を最初に照合する] を選択します。 リンクされた親を検索するには、[リンクされた作業項目を最初に照合する] を選択します。

作業項目のツリーのクエリ エディター ビューのスクリーンショット。

タスク、バグ、イシュー、フィーチャーなど、追跡対象となっている他の作業に依存する作業項目を追跡するには、[作業項目とダイレクト リンク] クエリを使用します。 たとえば、実装中の他の項目や修正中のバグに依存するバックログ項目を表示できます。

チーム間の依存関係を追跡するには、ダイレクト リンク クエリを使用します。 このクエリは、チームが行うコミットメントを管理するのにも役立ちます。 最上位およびリンクされた作業項目のフィルター条件を選択してください。 また、依存関係をフィルター処理するリンクの種類を選択してください。

ダイレクト リンク クエリの結果のスクリーンショット。

クエリ エディターのスクリーンショット (ダイレクト リンク クエリ)。

次のオプションのいずれかを選択して、作業項目の第 1 層リストをフィルター処理します。

  • [一致するリンクが定義されている項目だけを戻す]: 第 1 層の作業項目のうち、リンクされた作業項目のフィルター条件で指定された作業項目へのリンクが定義されているものだけを返します。
  • [最上位の項目すべてを戻す]: リンクされた作業項目のフィルター条件に関係なく、第 1 層のすべての作業項目を返します。 第 1 層にリンクされた第 2 層の作業項目は、作業項目のフィルター条件に一致する場合に返されます。
  • [一致するリンクが定義されていない項目だけを戻す]: 第 1 層の作業項目のうち、リンクされた作業項目のフィルター条件で指定された作業項目へのリンクが定義されていないものだけを返します。

各リンクの種類の詳細については、リンクの種類のリファレンスに関するページを参照してください。

AND/OR 論理式を使用する

クエリ句の論理式を作成するには、And または Or を指定します。 現在の句と前の句の両方の条件を満たす作業項目を検索するには、And を使用します。 現在の句か前の句のいずれかの条件を満たす作業項目を検索するには、Or を使用します。

作業項目フィールドごとに 1 つの新しい句を追加して、検索条件を絞り込みます。 必要な作業項目のセットのみが返されるように句を追加します。 クエリで期待どおりの結果が得られない場合は、対象を絞り込みます。 クエリ句を追加、削除、グループ化、またはグループ解除することで、クエリの結果を改善できます。

クエリ句をグループ化すると、それらはクエリの残りの部分とは別の 1 つのユニットとして動作します。 句のグループ化は、数学の方程式や論理式の一部をかっこで囲むのと似ています。 句をグループ化すると、グループ内の最初の句の And または Or がグループ全体に適用されます。

句のグループ化

グループ化されたクエリ句は、クエリの残りの部分とは別の 1 つのユニットとして動作します。 句のグループ化は、数学の方程式や論理式の一部をかっこで囲むのと似ています。 グループ内の最初の句の And または Or 演算子は、グループ全体に適用されます。

次の例に示すように、グループ化された句は対応する論理式に変換されます。

クエリ グループ化された句 論理式
1 グループ句クエリを示すスクリーンショット。[作業項目の種類] フィールドと、[状態] フィールドまたは [担当者] フィールドに対してフィルターが設定されます。 論理式のスクリーンショット。AND 演算子は、[作業項目の種類]、[状態]、および [担当者] フィールドをグループ化します。OR 演算子は、[状態] および [担当者] フィールドをグループ化します。
2 グループ句のクエリを示すスクリーンショット。[作業項目の種類] フィールドと、[状態] フィールドまたは [担当者] フィールドのいずれかに対するフィルターがあります。 論理式のスクリーンショット。AND 演算子は、OR 演算子によってグループ化された [状態] または [担当者] フィールドで作業項目の種類をグループ化します。
3 グループ句クエリを示すスクリーンショット。[作業項目の種類] フィールドか、[状態] フィールドと [担当者] フィールドの両方に対してフィルターが設定されます。 論理式のスクリーンショット。OR 演算子は、AND 演算子によってリンクされた [状態] および [担当者] フィールドの両方に作業項目の種類をリンクします。

これらのクエリは、種類が Bug で、次の論理式を満たす作業項目を返します。

  • クエリ 1: AND State=Active OR Assigned to @Me
  • クエリ 2: AND (State=Active OR Assigned to @Me)
  • クエリ 3: OR (State=Active AND Assigned to @Me)

1 つまたは複数の句をグループ化するには、それらを選び、 (句のグループ化) アイコンを選択します。

Web ポータル、クエリ エディター、[選択されたクエリ句をグループ化する] のスクリーンショット。

複数のグループ化された句をグループ化することもできます。 各句のチェック ボックスをオンにしてください。 その後、 (句のグループ化) アイコンを選択します。

Web ポータル、クエリ エディター、複数のクエリ句のグループ化のスクリーンショット。

クエリ結果で期待される結果が返されない場合は、次の手順を行います。

  • それぞれの句が意図したとおりに定義されていることを確認します。
  • 各句の And/Or 割り当てを確認します。 予期していた数よりも多くの作業項目が結果に含まれるときは、多くの場合、And 句ではなく Or 句が存在します。
  • クエリ句をグループ化するか、クエリ句のグループとグループ化されたそれぞれの句の And/Or の割り当てを変更する必要があるかどうかを判断します。
  • クエリ句をさらに追加し、クエリのフィルター条件を絞り込みます。
  • フィールド、演算子、および値を指定するためのオプションを確認します。
  • この記事の後半のベスト プラクティスを参照してください。

句のグループ解除

句のグループ化を解除するには、グループ化された句の (句のグループ解除) アイコンを選択します。

ダッシュボードでクエリ結果を表示する

クエリ結果は、次の 2 つのウィジェットで表示されます。 作業項目は、これらのウィジェットから直接開くことができます。

  • 自分に割り当てられた作業: サインインしているユーザーに割り当てられている提案済みまたはアクティブな作業項目をすべて一覧表示します。 [ID]、[状態]、および [タイトル] の各フィールドが一覧表示されます。
  • クエリ結果ウィジェット: フラット、ツリー、またはダイレクト リンクのクエリの結果を表示します。 ウィジェットを通じて表示されるフィールドを構成したり、列フィールドのサイズを変更したり、ツリー クエリやダイレクト リンク クエリを展開したり折りたたんだりすることができます。

詳細については、「ダッシュボードにウィジェットを追加する」を参照してください。

クエリ結果ウィジェットに親のタイトルを表示する

[親] のタイトルが表示された状態でクエリ結果を表示することもできます。 これを行うには、次の手順を実行します。

  1. 目的の作業項目に絞り込むためのクエリを作成します。 クエリには、フラット リスト、ツリー、またはダイレクト リンク クエリを指定できます。
  2. [親] フィールドを列として追加します。
  3. クエリを共有クエリまたはチームのお気に入りとして保存します。
  4. クエリ結果ウィジェットをダッシュボードに追加し、クエリを構成します。 [親] フィールドが表示されるように設定されていることを確認します。

次の図は、[親] フィールドを表示するクエリ結果ウィジェットを示しています。

親列フィールドを示すクエリ結果ウィジェットのスクリーンショット。

クエリ ハイパーリンクでは作業項目クエリ言語 (WIQL: Work Item Query Language) が使用されます。これは Transact-SQL に似ています。 詳細については、「作業項目クエリ言語 (WIQL) の構文」を参照してください。

Note

ほとんどのブラウザーでは、URL 文字列に対して 2000 から 2083 文字の制限が適用されます。

URL 構文の WIQL 部分をエンコードします。 任意の URL エンコーダー ツールを使用して、URL をエンコードできます。

https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

たとえば、次のハイパーリンクでは、Fabrikam 組織の FabrikamFiber/Web 区分パスに定義されているすべてのアクティブなバグの ID とタイトルが一覧表示されます。

https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'

デコードされた WIQL は次に準拠しています。

SELECT [System.ID], [System.Title]
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug'
   AND [System.State]='Active'
   AND [System.AreaPath]='FabrikamFiber\Web'

Note

Azure Boards クエリの場合、WIQL の長さは 32,000 文字を超えることはできません。

https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

たとえば、次のハイパーリンクでは、FabrikamFiber/Web 区分パスのすべてのバグの ID、タイトル、状態が一覧表示されます。

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20

例については、次の非エンコード エントリを参照してください。

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=
SELECT [System.ID], [System.Title], [System.State] 
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug' 
   AND [System.AreaPath]='FabrikamFiber\Web'

ベスト プラクティス

次のベスト プラクティスは、作成できる以下のクエリに適用されます。

集中型で選択的なクエリを作成する

クエリに必要なすべてのフィルターを適用して、選択性の高いクエリを定義します。 クエリの選択性が高ければ高いほど、結果セットは小さくなります。 結果セットが小さくなればなるほど、クエリの対象が絞られ、選択性が高まります。

タグを使って作業項目を分類する

カスタム フィールドではなく、作業項目タグを使って作業項目を分類します。 タグでフィルター処理するクエリは、通常、文字列の一致でフィルター処理するクエリよりも高速に実行されます。

カスタム フィールドの一致や部分一致とは異なり、Tags Contains 操作によるクエリは、すべての作業項目テーブルの完全なスキャンは必要ありません。

文字列の一致に Contains words を使う

文字列の一致でフィルター処理するには、Contains 演算子ではなく Contains Words を使います。 Contains Words 演算子は、指定されたフィールドの全文検索を実行し、より速く完了する傾向があります。

Contains 演算子ではテーブル スキャンが実行され、処理は Contains Words 演算子の場合よりも遅くなります。 また、より多くの CPU サイクルを消費します。 これらの CPU サイクルにより、レート制限が発生する可能性があります。 詳細については、「レートと使用量の制限」を参照してください。

In Group 演算子で小さなグループを指定する

In Group 演算子は、値のグループ内の一致に基づいて作業項目をフィルター処理します。 値のグループは、チーム、セキュリティ グループ、または作業追跡カテゴリに含まれる値に対応します。 たとえば、チームのメンバーに割り当てられているすべての作業項目を検索するクエリを作成できます。 または、要件カテゴリ (Microsoft.RequirementCategory) に属するすべての作業項目を検索します。

多数のメンバーを含むグループでフィルター処理すると、結果セットが大きくなり、非選択的になる傾向があります。 また、グループが大規模な Microsoft Entra グループに対応する場合、クエリでは Microsoft Entra ID からそのグループを解決するためにかなり大きなコストが発生します。

否定演算子の使用を避ける

<>, Not In, Not Under, Not In Group などの否定演算子では、非選択的なクエリや大きな結果セットが生成される傾向があります。

必要な場合にのみ、否定演算子を使用します。 常に、最初に代替案を見つけるようにします。 たとえば、Field1 に値 A、B、C、D がある場合、Field1 <> D 句を否定する代わりに、Field1 In A, B, C 句を指定します。

文字列比較を避ける

文字列比較を含むクエリでは、本質的に非効率的なテーブル スキャンが生成されます。 特にクエリのパフォーマンスが低い場合は、タグや特定のカスタム フィールドを代わりに使うことをお勧めします。

Or 演算子を制限する

クエリで定義される Or 演算子の数を制限します。 クエリは、Or 演算子を使う数が少ないほど、うまく動作します。 Or 演算子が多すぎると、クエリが非選択的になる可能性があります。 クエリの実行速度が遅い場合は、Or 演算子句をクエリ句の先頭に並べ替えます。

クエリを保存する

内部最適化により、保存したクエリは保存していないクエリよりもパフォーマンスが向上する傾向があります。 クエリを再利用する予定がある場合は、常にクエリを保存します。 WIQL クエリが REST API を介して実行される場合でも、Web ポータルを介して WIQL を保存して REST API 呼び出しを行うため、、将来のパフォーマンス低下が起こりにくくなります。

クエリを実行する

場合によっては、適切な最適化プランに到達するのにクエリを数回実行する必要があります。 必ず、クエリを保存し、30 分間に最大 10 回実行してください。 これにより、システムでは、クエリに最も適した最適化プランを調べて探し出すことができます。