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 などの変数、または 1/1/2023 などの値を指定できる日付フィールド。 個人プロファイルで設定した日付パターンで日付を入力します。 (詳細については、「個人用の設定」をご覧ください。)その他のクエリ例については、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 演算子を使って複数の値を指定します。 プロジェクトのツリー構造 (区分パスとイテレーション パス) を定義してから、チームに関連付けるものを選びます。

クエリの作成について詳しくは、「区分またはイテレーション パスによるクエリの実行」または「日付または現在のイテレーションによるクエリの実行」をご覧ください。

注意

1. picklist... データ型は、継承されたプロセスに対して定義されたカスタム フィールドにのみ割り当てられます。 継承されたプロセス モデルは、Azure DevOps Services と Azure DevOps Server 2019 だけでサポートされています。

日付と時刻のパターン

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

クエリ演算子

次の表のクエリ演算子を使用すると、句内の各値を対応する作業項目内の値に関連付ける方法を指定できます。 作業項目のフィールドに割り当てられるデータ型について詳しくは、作業項目フィールド リファレンスに関する記事をご覧ください。

句の追加と And/Or 演算子の使用については、「クエリの定義」をご覧ください。

クエリ演算子

作業項目の値が抽出条件と一致した場合に作業項目が返される

適用可能なデータの種類

=

句内の値と一致する。

Number (Double、GUID、Integer を含む)、String、DateTime、TreePath

<>

句内の値と一致しない。

Number、String、DateTime、TreePath

>

句内の値より大きい。

Number、String、DateTime

<

句内の値より小さい。

Number、String、DateTime

>=

句内の値より大きいか等しい。

Number、String、DateTime

<=

句内の値より小さいか等しい。

Number、String、DateTime

=[Field]

指定したフィールドに含まれる値と一致する。

指定されたフィールドと同じデータ型のフィールドの名前

<>[Field]

指定したフィールドに含まれる値と一致しない。

指定されたフィールドと同じデータ型のフィールドの名前

>[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 2019 以降のバージョンでサポートされています。

HTML

Is Not Empty

HTML フィールドに何らかの内容が含まれる作業項目の一覧を取得する。 この演算子では値を指定しません。 この演算子は、Azure Boards (クラウド サービス) と Azure DevOps Server 2019 以降のバージョンでサポートされています。

HTML

含まれない

区切られたセットのどの値とも一致しない。 [状態] フィールドで解決済み、完了済み、またはクローズ済みの値を指定した場合、状態がそれらの値ではない作業項目をクエリ結果から除外できます。 値は、クライアント コンピューターに定義されている地域設定に対応するリスト区切り記号で区切ります。 たとえば、コンマ (,) を使用できます。

Not In 演算子は、Azure Boards と TFS 2018.2 以降のバージョンで使用できます。

Number、String、DateTime、TreePath

グループ内

句内のグループのメンバーである値と一致する。 グループは、チーム、セキュリティ グループ、または作業追跡カテゴリの名前に対応します。 たとえば、貢献者グループのメンバーまたはチームに割り当てられているすべての作業項目を検索するクエリを作成できます。 チーム グループは、チームを作成したときに作成されます。 チーム グループの名前は、<チーム プロジェクト名>\<チーム名> というパターンです。

クエリの例については、割り当てまたはワークフローの変更によるクエリの実行に関する記事をご覧ください。

システムで定義されているチーム、セキュリティ グループ、またはカテゴリの名前と一致する String。

注意

In Group 演算子は、String データ型を使っているフィールドまたは [作業項目の種類] フィールドでのみ使用できます。 また、Azure Boards アカウントが Microsoft Entra ID によってサポートされている場合は Microsoft Entra ID で定義されたグループを使用でき、オンプレミスのサーバー インスタンスが Active Directory によってサポートされている場合は Active Directory で定義されたグループを使用できます。

カテゴリのグループについては、「カテゴリを使用して作業項目の種類をグループ化する」をご覧ください。

グループ外

句内のグループのメンバーである値と一致しない。

Team Foundation Server のユーザー グループまたはプロジェクトで定義されているカテゴリ グループの名前と一致する String。

注意

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 2019 以降のバージョンでサポートされます。

---

@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 2019 以降のバージョンでサポートされます。

---

@Today

DateTime フィールドで使って、現在の日付または以前の日付に関連する作業項目にフィルター処理します。 また、日数を引くことで @Today マクロを変更することもできます。 たとえば、Created Date>=@Today-7 句を使うと、過去 1 週間に作成されたすべての項目を見つけることができます。 他の例については、日付または現在のイテレーションによるクエリの実行に関する記事をご覧ください。

---

注意

1. @MyRecentActivity、@RecentMentions、@RecentProjectActivity マクロは、TFS 2018.2 以降のバージョンでサポートされています。
2. @StartOfDay、@StartOfWeek、@StartOfMonth、@StartOfYear マクロは、Azure DevOps Server 2019 Update 1 以降のバージョンでサポートされています。

フルテキスト検索と単語の一部の検索

単語や語句の完全一致または部分一致を検索するには、Contains または Does Not Contain を指定します。 これらの演算子は、長いテキスト フィールドに対して作成されたフルテキスト検索インデックスに基づいて項目をフィルター処理します。 語句に対する完全一致を検索したり、ワイルドカード文字 * を使ったりするには、Contains Words または Does Not Contain Words を指定します。 これらの演算子では全文検索インデックスが使用されます。 ワイルドカード文字は、単語や語句の一部である文字列の末尾でのみ使用できます。

例については、作業項目クエリの例および [履歴] フィールドを使用した作業項目のクエリに関する記事をご覧ください。

注意

すべての配置でフルテキスト検索がサポートされるとは限りません。 たとえば、クラウド サービスをサポートする SQL Express と SQL Azure では、フルテキスト検索はサポートされません。 これらのインスタンスでは、Contains と Does not Contain 演算子だけが表示されます。

関連記事

• クエリのクイック リファレンス
• マネージド クエリについて
• 作業項目フィールドのインデックス
• 作業項目クエリ言語 (WIQL) の構文

REST API

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

• Azure DevOps Services REST API リファレンス
• クエリ
• 作業項目クエリ言語
• プログラムでクエリを使って作業項目をフェッチする