Azure Boards と Azure DevOps でタイトル、ID、リッチ テキスト フィールドを使ってクエリを実行する

  • [アーティクル]

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

キーワード、語句、または null テキスト フィールドに基づいて作業項目を検索したい場合は、単一行テキスト (String)、複数行テキスト (PlainText)、リッチ テキスト (HTML) フィールドを使ってフィルター処理できます。 クエリが結果を返すのに時間がかかりすぎる場合は、「クエリの作成/ベスト プラクティス」を参照してください。

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

テキスト フィールドまたはリッチ テキスト フィールドを指定するクエリ句では、次の表で示す演算子とマクロを使用できます。

データの種類

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

リッチ テキスト (HTML)
複数行テキスト文字列 (PlainText)

Contains Words、Does Not Contain Words、Is Empty1、Is Not Empty1

単一テキスト (文字列)

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Everマクロ: [Any] ([作業項目の種類] フィールドで有効)、@Project2 ([チーム プロジェクト] フィールドで有効)。

ID

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Everマクロ: @Follows、@MyRecentActivity、@RecentMentions、@RecentProjectActivity ([ID] フィールドおよび In、Not In 演算子で有効)、@Project2 ([チーム プロジェクト] フィールドで有効)。

[状態] および [作業項目の種類] フィールド

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever **Macros**:[Any]` (両方のフィールドで有効)。

注意

  1. Is Empty と Is Not Empty 演算子は、Azure DevOps Server 2019 RC2 以降のバージョンでサポートされています
  2. 既定では、現在のプロジェクトに基づいて自動的にフィルター処理されます。 詳細については、プロジェクト間でクエリを実行に関するページをご覧ください。

文字列の一致に Contains words を使用する

文字列の一致でフィルター処理する場合は、Contains ではなく Contains Words 演算子を使ってみてください。 Contains Words 演算子は、指定されたフィールドに対してフルテキスト検索を実行します。これは、ほとんどの場合、高速です。 テキスト文字列は、100 文字までに制限されています。

これに対し、Contains 演算子ではテーブル スキャンが実行されますが、これは低速であるだけでなく、CPU サイクルの消費量も増えます。 これらの CPU サイクルは、リソース消費率の制限に近づく一因になります。

Note

Contains Words 演算子は、SQL のフルテキスト検索インデックス作成を使用します。 新しい値が長文フィールドに保存されると、SQL Server は次の操作を行います。

  • フレーズを個々の単語に分割する
  • 検索に実際に意味を追加しない一般的な単語の削除 (英語の "a" や "is" など)
  • 単語を共通の語幹に変換する (たとえば、running、ran、runner などは、すべて同一の単語のバリエーションであるため、"run" に変換されます)。
  • これらの一意のキーワードをインデックスに格納します。

その後、ユーザーが Contains Words 演算子を使用してこのフィールドに対してクエリを実行すると、インデックスに格納されている一意のキーワードに対して検索が実行されます。 長文フィールドの場合、これにより、部分文字列検索を行うよりもはるかに効率的かつ迅速に検索できます。 既定では、SQL では、"word" (単語) が句読点間の文字セットとして定義されます。 たとえば、ピリオドは単語の終わりを表しますが、ピリオドは単語の一部とは見なされません。 フルテキスト検索インデックスには正確な語句ではなくキーワード (keyword) が含まれているため、インデックス作成によって決定された同じキーワードを含むすべての結果が取得されます。

ワイルドカードを使用したキーワードまたは語句のクエリ

Contains または Contains Words を使うと、入力した単語や語句と部分一致または完全一致する項目の一覧を表示できます。

キーワードをフィルター処理するためのフラット リスト クエリ用のエディター。

単語や語句に対する完全一致または部分一致を検索するには、Contains または Does Not Contain を選びます。 完全な句を検索する場合や、ワイルドカード文字 * を使う場合は、Contains Words または Does Not Contain Words を選びます。 これらの演算子では全文検索インデックスが使用されます。

たとえば、inform または information または informational を含むテキスト フィールドでフィルター処理するには、Contains Words と inform* を指定します。

Contains Words でワイルドカードを使う。

ヒント

AND/OR 句をグループ化する方法については、マネージド クエリの作成と保存に関する記事の「句のグループ化」を参照してください。 クエリの WIQL 構文を表示するには、WIQL クエリ エディター拡張機能をインストールします。これにより、クエリ エディター エントリの WIQL バージョンを表示できます。

他の単語を含まない特定の単語だけのクエリを実行する

入力した単語または語句と完全に一致する項目の一覧を表示し、他の単語や語句を除外するには、Contains Words と Does Not Contain Words 演算子を使います。 これらの演算子は、ワイルドカード文字 (*) と組み合わせて使用できます。

次の例では、これらの演算子を使って、作業項目から単語 Phase を含むが単語 Phasor を含まない項目をフィルター処理します。

正確な単語を含めたり除外したりするクエリ エディターのスクリーンショット。

未定義フィールド値のクエリ

等号演算子 (=) を使い、フィールドの値を空白にすることで、未定義のフィールド値を持つ作業項目を見つけることができます。 たとえば、次のフィルターでは、[アクティビティ] フィールドが空白になっていて、種類がタスクであるすべての作業項目の一覧が表示されます。

空のカテゴリによるフィルター処理

空白でないフィールドに基づいて作業項目を一覧表示するには、not 演算子 (<>) を使い、値を空白のままにします。

空の HTML フィールドまたは空でない HTML フィールドのクエリ

[説明] が入力されていない作業項目を見つけることができます。 HTML フィールドで Is Empty または Is Not Empty を使うと、空の、または空ではないリッチ テキスト フィールドを含む作業項目の一覧を表示できます。 この演算子では値を指定しません。

たとえば、次のクエリ フィルターでは、[説明] フィールドに何かが入力されているすべての作業項目の一覧が表示されます。

空でない HTML フィールドに基づくフィルター処理

注意

タグが一切アタッチされていない作業項目のクエリを実行する機能はサポートされません。 この機能のサポート要求に賛成投票したい場合は、Developer Community ページの「Be able to search for empty tags」でできます。

カテゴリ ベースのクエリ

属しているカテゴリに基づいて作業項目をフィルター処理するには、In Group 演算子を使います。 たとえば、次のフィルター条件では、現在のプロジェクトにあり、そのチーム メンバーに割り当てられていて、Bug Category に属すると定義されているすべての作業項目が返されます。

カテゴリ別に作業項目を検索するクエリ列

要件またはタスクのカテゴリに表示される項目

各プロセスについて、各カテゴリへの作業項目の種類の既定の割り当てを以下に示します。

Process 要件カテゴリ タスクのカテゴリ
Basic 問題 タスク
アジャイル ユーザー ストーリー タスク
スクラム プロダクト バックログ項目、バグ タスク
CMMI 要件 タスク

バグ作業項目の種類を、要件またはタスクのいずれのカテゴリに表示するかは、チームごとに決定できます。 「バックログとボードにバグを表示する」を参照してください。 カスタム作業項目の種類をバックログに追加できます。 詳細については、「作業項目の種類を追加して変更する、カスタム WIT をバックログまたはボードに追加する」を参照してください。

フォローしている作業項目のクエリ

@Follows マクロを使うと、他のクエリ フィルターと共に、フォローしている作業項目に基づいて一覧をフィルター処理できます。

たとえば、次に示すクエリは、すべてのプロジェクトで、自分がフォローしているアクティブな作業項目のクエリを実行する方法です。 [ID] フィールドと In 演算子を、@Follows マクロと共に使っています。

ID、In、@Follows のクエリ句が示されているクエリ エディター

最近の作業項目のアクティビティのクエリ

次のマクロを使うと、最近のアクティビティに基づいて作業項目の一覧を表示できます。

  • @MyRecentActivity: 自分が最近表示または変更した項目の一覧を表示します。
  • @RecentMentions: 過去 30 日間に @mention を使って追加された項目の一覧を表示します。
  • @RecentProjectActivity: 自分のプロジェクトで最近作成または変更された項目の一覧を表示します。

[ID] フィールドと、In または Not In 演算子を指定します。

たとえば、次に示すのは、自分が最近表示または変更した作業項目のクエリを実行する方法です。

ID、In、@MyRecentActivity のクエリ句が示されているクエリ エディター

ほとんどの作業項目の種類に共通のフィールド

次の表では、クエリのフィルター処理に使われる一般的なフィールドについて説明します。 [ID] フィールドは、一覧内の作業項目を一意に識別します。 作業項目を同じ種類の他のすべてのものと区別するには、[タイトル] フィールドを使います。 [説明] や他のリッチ テキスト (データ型 =HTML) フィールドでは、作業の実装と変更の追跡に必要な追加情報が提供されます。 [ID] を除くすべてのフィールドは、作業項目を作成した後で変更できます。 作業項目を追加して保存すると、システムによって ID が割り当てられ、この ID は変更できません。

注意

データ型が PlainText と HTML であるすべての長いテキスト フィールドには、フルテキスト検索のため、システムによってインデックスが自動的に作成されます。 これには、[タイトル]、[説明]、[再現させるステップ] フィールドが含まれます。 詳細と、オンプレミスの Azure DevOps に適用されるサーバーと照合順序の要件については、クエリのフィールド、演算子、値、変数に関する記事の「フルテキスト検索と単語の一部の検索」をご覧ください。

フィールド名

説明

作業項目の種類

受け入れ基準1

バグまたはプロダクト バックログ項目を終了する前に、満たされている必要がある条件の説明。

バグまたはプロダクト バックログ項目について作業を開始する前に、顧客の受け入れ基準はできる限り明確に記述されている必要があります。 受け入れ基準を定義するためにチームと顧客との間で行われた会話は、顧客が期待している内容をチームが理解するうえで役に立ちます。 受け入れ基準は受け入れテストの土台として使用できるため、ユーザー ストーリーを完成させることができたかどうかをより効果的に評価できます。

参照名=Microsoft.VSTS.Common.AcceptanceCriteria、データ型=HTML

バグ、エピック、フィーチャー、プロダクト バックログ項目 (スクラム)

説明 1、2

作業項目に関する詳細な情報を提供するには、このフィールドを使います。

参照名=System.Description、データ型=HTML

すべて

id

作業項目に割り当てられる一意の識別子。 作業項目 ID は、すべてのプロジェクトおよびプロジェクト コレクション内で一意です。

参照名=System.Parent、データ型=Integer

すべて

再現ステップ (または再現手順) 1

予測できない動作の再現に必要な手順。 他のチーム メンバーが問題の影響を正確に理解し、バグが修正済みかどうかを判断するために十分な情報を提供します。 これには、バグの検出や再現に必要な操作と、予想される動作が含まれます。
参照名=Microsoft.VSTS.TCM.ReproSteps、データ型=HTML

Bug

解像度

懸案事項がどのように解決されたかを説明します。

参照名=Microsoft.VSTS.Common.Resolution、データ型=HTML

障害 (スクラム)

システム情報1

バグ、コード レビュー、またはフィードバックに関連するソフトウェアとシステム構成に関する情報。

参照名=Microsoft.VSTS.TCM.SystemInfo、データ型=HTML

バグ、コード レビュー要求、フィードバック要求

チーム プロジェクト

作業項目が属しているプロジェクト。 1 つ以上のプロジェクトの項目で一覧をフィルター処理する場合は、このフィールドをクエリに追加します。 詳細については、「クエリ例、複数プロジェクトにわたるクエリ」をご覧ください。

参照名=System.TeamProject、データ型=String

すべて

Title

作業項目の内容をまとめた簡単な説明。チーム メンバーはこの説明を参考にして、作業項目をリスト内の他の作業項目と区別できます。

参照名=System.Title、データ型=String

すべて

作業アイテムの種類

作業項目の種類の名前。 作業項目の種類は、プロジェクトの作成時に使われたプロセスに基づいて定義されます。 詳しくは、「プロセスとプロセス テンプレートについて」と「作業項目の種類の追加または変更」をご覧ください。

カテゴリの割り当てに基づいて作業項目をフィルター処理するには、In Group と Not In Group 演算子を使い、ドロップダウン リストからカテゴリを選びます。

参照名=System.WorkItemType、データ型=String

すべて

Note

Team Foundation Server 2012 へのアップグレード時に、[説明] フィールドの型が PlainText から HTML に変更されました。 witadmin changefield コマンドを使うと、このフィールドのデータ型を元に戻すことができます。 「作業項目フィールドの管理」 (witadmin) をご覧ください。

REST API

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