Azure Boards でフィールド、演算子、およびマクロのクエリを実行する
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
この記事では、各フィールドのデータ型、クエリ演算子、およびクエリ マクロについて説明します。 一部のデータ型、演算子、マクロは、示されている Azure DevOps のバージョンでのみ有効です。
詳細については、クエリに関するクイック リファレンスと、クエリの管理および整理に関する記事を参照してください。
クエリのフィールドのデータ型と値
各フィールドに指定する値は、そのフィールドのデータ型に適合している必要があります。 次の表は、サポートされるデータ型の一覧を示します。
注意
Azure Boards クラウド サービスの場合、データ型は [プロセス] > [フィールド] ページでフィールドに対して一覧表示されるデータ型に対応します。 オンプレミスの展開の場合、データ型は FIELD 定義に割り当てられた type 属性に対応します。 詳しくは、作業項目のフィールドとフィールド属性に関する記事をご覧ください。
データの種類
説明
Boolean
True と False の値を受け取るフィールドを指定します。
DateTime または Date/Time
@Today や @Today-1 などの変数、01/01/2025 などの値を指定できる日付フィールド。 個人プロファイルで設定した日付パターンで日付を入力します。 (詳細については、「個人用の設定」をご覧ください。)その他のクエリ例については、Query by date or @CurrentIteration に関する記事を参照してください。
WIQL クエリの場合は、協定世界時 (UTC) のパターンで日付を指定することもできます。 詳細については、「作業項目クエリ言語 (WIQL) の構文」を参照してください。
Double または Decimal
0.2、3.5 などの実数。 クエリの例については、数値フィールドによるクエリに関する記事をご覧ください。
GUID
一意の ID を表す文字列。
HISTORY
履歴情報を追跡するために使用されるカスタム書式のフィールド。 このデータ型は、[履歴] フィールドをサポートするためにのみ使われます。 フルテキスト検索が利用可能な場合は、このフィールドに対してフルテキスト検索用のインデックスが自動的に作成されます。 この記事で後に出てくる「フルテキスト検索と単語の一部の検索」をご覧ください。 クエリの例については、履歴と監査に関する記事をご覧ください。
HTML
[説明] または [再現ステップ] フィールドなどの書式設定された説明をサポートするテキスト文字列。 フルテキスト検索が利用可能な場合は、これらのフィールドに対してフルテキスト検索用のインデックスが自動的に作成されます。 この記事で後に出てくる「フルテキスト検索と単語の一部の検索」をご覧ください。 リッチ テキスト フィールドのクエリについては、タイトル、ID、リッチ テキスト フィールドによるクエリに関する記事をご覧ください。
ID
ユーザー ID を示す短いテキスト文字列。
整数
0、1、2、34 などの符号付き 32 ビット整数。
PlainText または Text フィールド (複数行)
[アプリケーション開始情報] フィールドなどの長い説明をサポートするテキスト文字列。 フルテキスト検索が利用可能な場合は、これらのフィールドに対してフルテキスト検索用のインデックスが自動的に作成されます。 この記事で後に出てくる「フルテキスト検索と単語の一部の検索」をご覧ください。 プレーンテキスト フィールドのクエリについては、タイトル、ID、リッチ テキスト フィールドによるクエリに関する記事をご覧ください。
picklistDouble
Decimal 値の候補リストを格納するように定義されたカスタム フィールド。
picklistInteger
Integer 値の候補リストを格納するように定義されたカスタム フィールド。
picklistString
短いテキスト文字列 (255 文字以下) の値の候補リストを格納するように定義されたカスタム フィールド。
String または Text フィールド (単一行)
最大 255 文字の Unicode 文字を含む短いテキスト文字列。 String テキスト フィールドは、候補リストまたはドロップダウン メニューをサポートするためによく使われます。
TreePath
区分パスやイテレーション パスなどの分岐ツリー構造。 有効な値の一覧から項目を選びます。 ツリー構造と等しい、ツリー構造と等しくない、ツリー構造以下にある、またはツリー構造以下にない作業項目を検索します。 In 演算子または Not In 演算子を使用して複数の値を指定することもできます。 プロジェクトのツリー構造 (区分パスとイテレーション パス) を定義し、チームに関連付けるものを選択します。
クエリの作成について詳しくは、「区分またはイテレーション パスによるクエリの実行」または「日付または現在のイテレーションによるクエリの実行」をご覧ください。
注意
picklist... データ型は、継承されたプロセスに対して定義されたカスタム フィールドにのみ割り当てられます。
日付と時刻のパターン
DateTime フィールドに入力する日付と時間のパターンは、プロファイルで選んだものと一致する必要があります。 選んだ内容を確認または変更するには、「ユーザーの優先設定を設定する」を参照してください。
![[時刻とロケール] ペインの [日付パターン] ドロップダウン オプションを示すスクリーンショット。](../../organizations/settings/media/user-preferences/date-patterns.png?view=azure-devops-2022)
![[時刻とロケール] ペインの [時刻パターン] ドロップダウン オプションを示すスクリーンショット。](../../organizations/settings/media/user-preferences/time-pattern.png?view=azure-devops-2022)
![[日付パターン] フィールドと [時刻パターン] フィールドを含む [時刻とロケール] ペインを示すスクリーンショット。](../../organizations/settings/media/user-preferences/jamalh-locale-settings-server.png?view=azure-devops-2022)
クエリ演算子
句の中の各値が作業項目内の対応する値とどのように関連するかを指定するには、次の表のクエリ演算子を使用します。 作業項目のフィールドに割り当てられるデータ型について詳しくは、作業項目フィールド リファレンスに関する記事をご覧ください。
詳細については、クエリの定義に関する記事を参照してください。
クエリ演算子
作業項目の値が抽出条件と一致した場合に作業項目が返される
適用可能なデータの種類
=
句内の値と一致する。
Number (Double、GUID、Integer を含む)、String、DateTime、TreePath
<>
句内の値と一致しない。
Number、String、DateTime、TreePath
>
句内の値より大きい。
Number、String、DateTime
<
句内の値より小さい。
Number、String、DateTime
>=
句内の値より大きいか等しい。
Number、String、DateTime
<=
句内の値より小さいか等しい。
Number、String、DateTime
=[Field]
指定したフィールドに含まれる値と一致する。
指定されたフィールドと同じデータ型のフィールドの名前
Boolean 型フィールドが別のフィールドと等しいかどうかを確認します
<>[Field]
指定したフィールドに含まれる値と一致しない。
指定されたフィールドと同じデータ型のフィールドの名前
Boolean 型フィールドが別のフィールドと等くないかどうかを確認します
>[Field]
指定したフィールドに含まれる値より大きい。
指定されたフィールドと同じデータ型のフィールドの名前
<[Field]
指定したフィールドに含まれる値より小さい。
指定されたフィールドと同じデータ型のフィールドの名前
>=[Field]
指定したフィールドに含まれる値より大きいか等しい。
指定されたフィールドと同じデータ型のフィールドの名前
<=[Field]
指定したフィールドに含まれる値より小さいか等しい。
指定されたフィールドと同じデータ型のフィールドの名前
Contains
フィルター処理の対象として選択したフィールドが、テキスト文字列に完全または部分的に一致する。
String
Does Not Contain
フィルター処理の対象として選択したフィールドが、テキスト文字列に完全にも部分的にも一致しない。
String
語を含む
フィルター処理の対象として選択したフィールドに、テキスト文字列または単語の完全一致が含まれる。 ワイルドカード文字 "*" を使用して、単語や語句の一部を入力することもできます。 テキスト文字列は、100 文字までに制限されています。 制限については、フルテキスト検索でのサーバーと照合順序の要件に関する説明を参照してください。
フルテキスト検索用のインデックスが作成されている長いテキスト フィールド。すべての PlainText と HTML フィールド、および History と Title フィールドに対応します。
語を含まない
フィルター処理の対象として選択したフィールドに、テキスト文字列または単語の完全一致が含まれない。 テキスト文字列は、100 文字までに制限されています。
この演算子を Contains Words 演算子を含む句と組み合わせて使用し、特定のキーワードを含めたり除外したりします。
フルテキスト検索用のインデックスが作成されるテキスト フィールド。
含まれる
区切られた値と一致する。 たとえば、ID が 100、101 および 102 の作業項目は、[ID] フィールドにこれらの値を指定すると検索できます。 値は、クライアント コンピューターに定義されている地域設定に対応するリスト区切り記号で区切ります。 たとえば、コンマ , を使用できます。
Number、String、DateTime、TreePath
Is Empty
空の HTML フィールドを含む作業項目の一覧を取得する。 この演算子では値を指定しません。 この演算子は、Azure Boards および Azure DevOps Server でサポートされています。
HTML
Is Not Empty
HTML フィールドに何らかの内容が含まれる作業項目の一覧を取得する。 この演算子では値を指定しません。 この演算子は、Azure Boards および Azure DevOps Server でサポートされています。
HTML
含まれない
区切られたセットのどの値とも一致しない。 状態が解決済み、完了、またはクローズでない作業項目をクエリ結果から除外するには、これらの値を状態フィールドに指定します。 値は、クライアント コンピューターに定義されている地域設定に対応するリスト区切り記号で区切ります。 たとえば、コンマ , を使用できます。
Not In 演算子は、Azure Boards および Azure DevOps Server でサポートされています。
Number、String、DateTime、TreePath
グループ内
句内のグループのメンバーである値と一致する。 グループは、チーム、セキュリティ グループ、または作業追跡カテゴリの名前に対応します。 たとえば、貢献者グループのメンバーまたはチームに割り当てられているすべての作業項目を検索するクエリを作成できます。 チーム グループは、チームを作成したときに作成されます。 チーム グループの名前は、<チーム プロジェクト名>\<チーム名> というパターンです。
クエリの例については、割り当てまたはワークフローの変更によるクエリの実行に関する記事をご覧ください。
システムで定義されているチーム、セキュリティ グループ、またはカテゴリの名前と一致する String。
注意
In Group 演算子は、String データ型を使っているフィールドまたは [作業項目の種類] フィールドでのみ使用できます。 また、Azure Boards アカウントが Microsoft Entra ID によってサポートされている場合は Microsoft Entra ID で定義されたグループを使用でき、オンプレミスのサーバー インスタンスが Active Directory によってサポートされている場合は Active Directory で定義されたグループを使用できます。
詳細については、カテゴリを使用して作業項目の種類をグループ化する方法に関する記事を参照してください。
グループ外
句内のグループのメンバーである値と一致しない。
Azure DevOps Server 内のユーザー グループまたはプロジェクトに定義されたカテゴリ グループの名前に一致する String。
Note
Not In Group 演算子は、String データ型を使っているフィールドまたは [作業項目の種類] フィールドでのみ使用できます。 また、Azure Boards アカウントが Microsoft Entra ID によってサポートされている場合は Microsoft Entra ID で定義されたグループを使用でき、オンプレミスのサーバー インスタンスが Active Directory によってサポートされている場合は Active Directory で定義されたグループを使用できます。
次の値の下ではない
句内の値と一致せず、かつ句内のノードの下に含まれない。
TreePath
Under
句内の値と一致するか、または句内のノードの下に含まれる。
TreePath
次の値と等しかったことがある
句内の値が前のいずれかと一致する。
String、DateTime
Note
クエリ エディターを使用する場合に、日付フィールドの Was Ever は現在サポートされていません。 これらは直接 WIQL でクエリを実行する場合にのみサポートされます。
ヒント
Was Ever などの演算子を使用する WIQL 構文を使用して、一覧に示されているデータ型フィールド以外のデータ型フィールドに対してクエリを作成できます。 たとえば、イテレーション パスを使う句で Was Ever を使用できます。 例については、日付または現在のイテレーションによるクエリの実行に関する記事の「スプリントから移動された作業項目の一覧を表示する」をご覧ください。
クエリのマクロまたは変数
次の表で説明するマクロを使うと、特定のフィールドに基づいてクエリをフィルター処理できます。
注意
次のマクロは、Web ポータルからのみサポートされています: @CurrentIteration、@CurrentIteration +/- n、@Follows、@MyRecentActivity、@RecentMentions、@RecentProjectActivity、@TeamAreas。 これらのマクロを含むクエリは、Visual Studio のチーム エクスプローラー、Microsoft Excel、または Microsoft Project で開くと機能しません。
マクロ
説明
[Any]
[作業項目の種類] または [状態] フィールドで使って、すべての作業項目の種類またはすべての状態を検索します。 たとえば、Work Item Type=[Any] では、作業項目タイプに基づくフィルターは一切適用されません。
@CurrentIteration
[イテレーション パス] フィールドで使い、現在のチームのフォーカスまたはコンテキストに基づいて、現在のスプリントに割り当てられている作業項目で自動的にフィルター処理します。 具体的な例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@CurrentIteration マクロは、Web ポータルから実行する場合にのみ機能します。 テスト スイートとテスト ケースをコピーまたは複製するとき、アラートを定義するとき、または REST API では、このマクロを使用できません。
@CurrentIteration +/- n
[イテレーション パス] フィールドで使い、現在のチームのフォーカスまたはコンテキストに基づいて、現在のスプリント +/- n スプリントに割り当てられている作業項目のセットをフィルター処理します。 具体的な例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@CurrentIteration +/- n マクロは、Web ポータルから実行する場合、Azure Boards および Azure DevOps Server でサポートされます。
@Follows
[ID] フィールドで In 演算子と共に使って、プロジェクトでフォローしているすべての作業項目の一覧を表示します。 詳細については、 作業項目または pull request のフォローに関する記事を参照してください。 この同じ一覧は、[作業項目] ページの [フォロー] ピボット ビューから見ることができます。
@Follows マクロは、Web ポータルから実行する場合にのみサポートされます。
@Me
ID またはユーザー アカウントのフィールドで使って、自分のユーザー名またはアカウント名に関連付けられている項目を自動的に検索します。 たとえば、Created By=@Me 句を使うと、自分で開いた作業項目を見つけることができます。 その他の例については、割り当て、ワークフロー、またはボードの変更によるクエリに関する記事を参照してください。
@MyRecentActivity
ID フィールドと In 演算子を使用して、過去 30 日以内にプロジェクトで表示または更新した作業項目を一覧表示します。 この同じ一覧は、[作業項目] ページの [マイ アクティビティ] ピボット ビューから見ることができます。
@Project
[チーム プロジェクト] フィールドで使って、他のプロジェクトの作業項目についてフィルター処理します。 たとえば、Team Project=@Project 句を使うと、現在選ばれているプロジェクト内のすべての作業項目を検索できます。 既定では、現在のプロジェクトに基づいて自動的にフィルター処理されます。 詳細については、クエリの定義に関する記事の複数のプロジェクトを対象とするクエリに関する説明をご覧ください。
@RecentMentions
ID フィールドと In 演算子を使用し、[ディスカッション] セクションで自身がメンションされている作業項目を一覧表示します。 この同じ一覧は、[作業項目] ページの [メンション] ピボット ビューから見ることができます。
@RecentProjectActivity
ID フィールドおよび In 演算子と共に使用して、最近更新された作業項目を一覧表示します。 表示される作業項目の数は、プロジェクトの作業追跡アクティビティによって異なります。 非常にアクティブなプロジェクトの場合、マクロにより、過去 30 日以内にプロジェクトで更新された作業項目が一覧表示されます。 一方、アクティブでないプロジェクトの場合は、30 日より前の作業項目がこの一覧に含まれる場合があります。 同様の一覧は、[作業項目] ページの [最近作成]、[最近更新]、[最近完了] の各ピボット ビューから見ることができます。 返される作業項目の数は 5,000 に制限されます。
@StartOfDay
DateTime フィールドで使って、現在の日付またはそれにオフセットを加減したものに関連する作業項目にフィルター処理します。 たとえば、Closed Date>=@StartOfDay-7 句を使うと、過去 1 週間に終了されたすべての項目を見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@StartOfMonth
DateTime フィールドで使って、現在の月またはそれにオフセットを加減したものに関連する作業項目にフィルター処理します。 たとえば、Created Date>=@StartOfMonth-3 句を使うと、過去 3 か月間に作成されたすべての項目を見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@StartOfWeek
DateTime フィールドで使って、現在の週またはそれにオフセットを加減したものに関連する作業項目にフィルター処理します。 たとえば、Changed Date>=@StartOfWeek-2 句を使うと、過去 2 週間に変更されたすべての項目を見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@StartOfYear
DateTime フィールドで使って、現在の年またはそれにオフセットを加減したものに関連する作業項目にフィルター処理します。 たとえば、Target Date>=@StartOfYear 句を使うと、目標とする日が今年にスケジュールされているすべてのフィーチャーを見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
@TeamAreas
[区分パス] フィールドでのみ使って、区分パスが特定のチームに割り当てられているものに対応する作業項目にフィルター処理します。 = 演算子を使う必要があります。 たとえば、Area Path=@TeamAreas [Fabrikam Fiber]\Web 句を使うと、Web チームに割り当てられた区分パスに割り当てられているすべての項目を検索できます。 他の例については、区分またはイテレーション パスによるクエリの実行に関する記事をご覧ください。
@TeamAreas マクロは、Web ポータルから実行される場合のみ、Azure DevOps Server でサポートされます。
@Today
DateTime フィールドで使って、現在の日付または以前の日付に関連する作業項目にフィルター処理します。 また、日数を引くことで @Today マクロを変更することもできます。 たとえば、Created Date>=@Today-7 句を使うと、過去 1 週間に作成されたすべての項目を見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。
フルテキスト検索と単語の一部の検索
単語や語句の完全一致または部分一致を検索するには、Contains または Does Not Contain を指定します。 これらの演算子は、長いテキスト フィールドに対して作成されたフルテキスト検索インデックスに基づいて項目をフィルター処理します。 語句に対する完全一致を検索したり、ワイルドカード文字 * を使ったりするには、Contains Words または Does Not Contain Words を指定します。 これらの演算子では全文検索インデックスが使用されます。 ワイルドカード文字は、単語や語句の一部である文字列の末尾でのみ使用できます。
例については、作業項目クエリの例および [履歴] フィールドを使用した作業項目のクエリに関する記事をご覧ください。
注意
すべての配置でフルテキスト検索がサポートされるとは限りません。 たとえば、クラウド サービスをサポートする SQL Express と SQL Azure では、フルテキスト検索はサポートされません。 これらのインスタンスでは、Contains と Does not Contain 演算子だけが表示されます。
Azure DevOps Server は、PlainText データ型と HTML データ型のすべての long-text フィールドと、Title フィールドに対して、フルテキスト検索用のインデックスを自動的に作成します。 インデックスと演算子は、Azure DevOps Server をサポートする SQL Server でフルテキスト検索がサポートされている場合にのみ使用できます。
フルテキスト検索では、SQL Server にワード ブレーカーが登録されている言語に対応する SQL 照合順序が必要です。 Azure DevOps Server インスタンスに使用されるプロジェクト コレクション データベースの照合順序設定が、サポートされている言語に対応していない場合、検索結果が期待どおりにならない可能性があります。 このような場合は、Contains または Does Not Contain 演算子を試すことができます。
詳しくは、「フルテキスト検索のクエリと照合順序の設定」をご覧ください。
関連記事
REST API
プログラムでクエリを操作するには、次の REST API リソースのいずれかを参照してください。