Azure DevOps サービス |Azure DevOps Server |Azure DevOps Server 2022
ヒント
初めてクエリを実行しますか? まず、手順については クエリの定義 を、例については クエリのクイック リファレンス を参照してください。
このリファレンス ガイドを使用して、クエリ エディターでクエリを作成するときにフィールド データ型、クエリ演算子、マクロ、変数を検索します。 すべての演算子とマクロは、Azure Boardsでサポートされています。一部の演算子は、特定のAzure DevOps Server バージョンにのみ適用されます。
簡単な例とエディター タスクについては、「 クエリクイック リファレンス 」および「 クエリの管理と整理」を参照してください。
必須コンポーネント
| カテゴリ | 必要条件 |
|---|---|
| プロジェクト メンバーシップ | プロジェクトの メンバーとして追加 する必要があります。 |
| アクセス レベル | - 共有クエリを表示して実行するには、Projectメンバーである必要があります。 - 共有クエリを追加して保存するには、少なくとも Basic アクセス権が必要です。 |
| Permissions | クエリを追加するフォルダーで、[共同作成] アクセス許可が [許可] に設定されていることを確認してください。 組織では、このアクセス許可を付与するために 共同作成者 グループを手動で構成する必要がある場合があります。 |
Note
共有クエリを保存するには、十分なアクセス レベルと 投稿 アクセス許可の両方が必要です。 基本的なアクセスでは不十分です。
| カテゴリ | 必要条件 |
|---|---|
| プロジェクト メンバーシップ | プロジェクトの メンバーとして追加 する必要があります。 |
| アクセス レベル | - 共有クエリを表示して実行するには、Projectメンバーである必要があります。 - 共有クエリを追加して保存するには、少なくとも Basic アクセス権が必要です。 |
| Permissions | クエリを追加するフォルダーで、[共同作成] アクセス許可が [許可] に設定されていることを確認してください。 組織では、このアクセス許可を付与するために 共同作成者 グループを手動で構成する必要がある場合があります。 |
Note
共有クエリを保存するには、十分なアクセス レベルと 投稿 アクセス許可の両方が必要です。 基本的なアクセスでは不十分です。
クエリのフィールドのデータ型と値
フィールドのデータ型と一致する値を指定します。 次の表に、サポートされているデータ型を示します。
Note
Azure Boards (クラウド) の場合、データ型は Process > フィールド ページに表示されるフィールドと一致します。 オンプレミスデプロイの場合、データ型はtype定義のFIELD属性に対応します。 詳細については、 作業項目フィールドとフィールド属性を 参照してください。
| データの種類 | Description |
|---|---|
| ブーリアン | 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 | 一意の識別子を文字列として格納します。 |
| 歴史 | 履歴情報用のカスタム書式設定フィールド (履歴フィールド) フルテキスト検索が使用可能な場合、このフィールドはフルテキスト クエリ用にインデックスが作成されます。 「履歴と監査」を参照してください。 |
| HTML | 説明や再現手順などの書式設定されたテキストを格納します。 フルテキスト検索が使用可能な場合、これらのフィールドにはインデックスが作成されます。 リッチ テキスト フィールドのクエリについては、タイトル、ID、リッチ テキスト フィールドによるクエリに関する記事をご覧ください。 |
| アイデンティティ | ユーザー ID を識別する短いテキスト文字列を格納します。 |
| 整数 | 0、1、2、34 などの符号付き 32 ビット整数を格納します。 |
| PlainText または Text フィールド (複数行) | アプリケーションの開始情報などの長いテキスト値を格納します。 これらのフィールドは、サポートされている場合にフルテキスト検索のインデックスを作成します。 「タイトル、ID、およびリッチ テキスト フィールドによるクエリ」を参照してください。 |
| picklistDouble | 10 進値の選択リストを保持するユーザー設定フィールド。 |
| picklistInteger | 整数値の選択リストを保持するユーザー設定フィールド。 |
| picklistString | 短いテキスト値 (255 文字以下) の選択リストを保持するユーザー設定フィールド。 |
| String または Text フィールド (単一行) | 最大 255 Unicode 文字の短いテキストを格納します。 チームは多くの場合、これらのフィールドを選択リストまたはプルダウンメニューに使用します。 |
| TreePath | 領域パスや反復パスなどの分岐ツリーを表します。 有効なノード値を選択します。 等値、不等値、"Under"、または "Not Under" をフィルター処理できます。複数の値を指定するには、 In 演算子と Not In 演算子を使用します。 プロジェクトのツリー構造 ( エリア パス と イテレーション パス ) を定義し、チームに関連付けるノードを選択します。 クエリの例については、「 領域または反復パスによるクエリ」 および 「日付または現在のイテレーションによるクエリ」を参照してください。 |
Note
picklist...型は、継承されたプロセスに対して定義されたユーザー設定フィールドにのみ適用されます。
日付と時刻のパターン
DateTime フィールドに入力する日付と時間のパターンは、プロファイルで選んだものと一致する必要があります。 選んだ内容を確認または変更するには、「ユーザーの優先設定を設定する」を参照してください。
![[時刻とロケール] ペインの [日付パターン] ドロップダウン オプションを示すスクリーンショット。](../../organizations/settings/media/user-preferences/date-patterns.png?view=azure-devops)
![[時刻とロケール] ペインの [時刻パターン] ドロップダウン オプションを示すスクリーンショット。](../../organizations/settings/media/user-preferences/time-pattern.png?view=azure-devops)
![[日付パターン] フィールドと [時刻パターン] フィールドを含む [時刻とロケール] ペインを示すスクリーンショット。](../../organizations/settings/media/user-preferences/jamalh-locale-settings-server.png?view=azure-devops)
クエリ演算子
演算子を使用して、作業項目のフィールド値に句値を関連付ける方法を定義します。 フィールド データ型については、 作業項目フィールド参照を参照してください。 クエリの作成については、「 クエリの定義」を参照してください。
| クエリ演算子 | 演算子が一致する作業項目を返す場合 | 適用可能なデータ型 |
|---|---|---|
| = | 式の値と一致します。 | 数値 (Double/Decimal/GUID/Integer)、String、DateTime、TreePath |
| <> | 句の値と一致しません。 | Number、String、DateTime、TreePath |
| > | 条件の値より大きい。 | Number、String、DateTime |
| < | 条件式の値より小さい。 | Number、String、DateTime |
| >= | 句の値以上である。 | Number、String、DateTime |
| <= | 句の値以下である。 | Number、String、DateTime |
| =[Field] | 別の指定されたフィールドの値と一致します (同じデータ型である必要があります)。 | 同じデータ型のフィールドの名前 (ブール型フィールドは、他のフィールドと等しい値を比較します)。 |
| <>[フィールド] | 別の指定されたフィールドの値と一致しません。 | 同じデータ型のフィールドの名前。 |
| >[フィールド] | 指定した別のフィールドの値より大きい値です。 | 同じデータ型のフィールドの名前。 |
| <[フィールド] | 指定した別のフィールドの値より小さい値です。 | 同じデータ型のフィールドの名前。 |
| >=[フィールド] | 指定した別のフィールドの値以上です。 | 同じデータ型のフィールドの名前。 |
| <=[フィールド] | 指定した別のフィールドの値以下です。 | 同じデータ型のフィールドの名前。 |
| 含む | テキストの完全一致または部分的一致を含みます。 | String |
| 含まれない | ぴったりまたは部分的に一致するテキストは見つかりません。 | String |
| 単語を含む | 正確な語句または単語と一致します (末尾のワイルドカード *をサポートします)。 制限: 100 文字。 この演算子はフルテキスト インデックス作成を使用します。サーバーと照合順序の要件については、この記事の「フルテキスト」セクションを参照してください。 |
フルテキスト検索用にインデックスが作成された長いテキスト フィールド (PlainText、HTML、History、Title)。 |
| 単語を含まない | 指定した語句を含む項目を除外します。 制限: 100 文字。 キーワードを含めたり除外したりするには、コンパニオン句の Contains Words と共に使用します。 |
フルテキスト検索用にインデックスが作成されたテキスト フィールド。 |
| 含まれる | 区切り記号付きセット内の任意の値と一致します (OS の地域リスト区切り記号 (通常はコンマ) を使用します)。 | Number、String、DateTime、TreePath |
| 空です | HTML フィールドにコンテンツが含まれていません (値が指定されていない) アイテムと一致します。 Azure BoardsとAzure DevOps Serverでサポートされます。 | HTML |
| 空ではない | HTML フィールドにコンテンツが含まれているアイテムと一致します。 Azure BoardsとAzure DevOps Serverでサポートされます。 | HTML |
| 含まれない | 区切り記号付きセット内の値を除外します (地域リストの区切り記号を使用します)。 Azure BoardsとAzure DevOps Serverでサポートされます。 | Number、String、DateTime、TreePath |
| グループ内 | 名前付きグループ (チーム、セキュリティ グループ、またはカテゴリ) のメンバーである値と一致します。 たとえば、パターン [Project Name]\Team Nameで名前が付けられた共同作成者グループまたはチーム グループを使用します。 例については、「 割り当てまたはワークフローの変更によるクエリ」 を参照してください。 [ グループ内] は、文字列型フィールドまたは作業項目の種類でのみ使用します。 Microsoft Entra ID グループは、アカウントでオンプレミスのMicrosoft Entra IDまたはActive Directory グループを使用する場合に使用できます。 |
文字列 (グループ名またはチーム名に一致) または作業項目の種類 |
| グループ外 | 名前付きグループのメンバーを除外します。 | ユーザー グループまたはプロジェクト カテゴリに一致する文字列。 |
| 次の値の下ではない | 指定したツリー ノードと同じか、または指定したツリー ノードの下に含まれている項目を除外します。 | TreePath |
| の下 | 指定したツリー ノードと等しいか、または指定したツリー ノードの下に含まれる項目と一致します。 | TreePath |
| かつてあった | フィールドが以前に保持していた値と一致します。 (クエリ エディター: 文字列フィールドのみ。DateTime のサポートには、直接 WIQL クエリが必要です)。) | String、DateTime |
ヒント
反復パスなどの他のデータ型に対して演算子 ( Was Ever など) を使用する WIQL クエリを作成できます。 例については、「 スプリントから移動された作業項目を一覧表示 する」を参照してください。
演算子の一般的な例
さまざまな演算子を使用する代表的なクエリ例を次に示します。
| Query | 返品 |
|---|---|
State = Active |
状態が "アクティブ" の作業項目 |
Priority <> Low |
優先度の低いアイテムを除くすべての項目 |
Created Date >= @Today-7 |
過去 7 日間に作成された作業項目 |
Assigned To = @Me |
現在のユーザーに割り当てられているアイテム |
Tags Contains "frontend" |
"フロントエンド" を含むタグを持つ項目 |
State In (Active, In Progress) |
いずれかの状態にある項目 |
Area Path Under "Project\Web" |
サブエリアを含む、Web 領域のすべての項目 |
Assigned To In Group "[Project]\Developers" |
開発者グループ内のすべてのユーザーに割り当てられたアイテム |
Description Contains Words "urgent" |
説明に "緊急" という単語が含まれている項目 |
フルテキスト検索と部分単語検索
含む または 含まない を使用して、長文フィールドに対して完全一致または部分一致を検索します。 これらの演算子はクエリ インデックスを使用します。 完全一致のフレーズを検索するには、「単語を含む」または「単語を含まない」を使用するか、末尾ワイルドカード（*）を使用します。 これらの演算子にはフルテキスト インデックスが必要です。
ワイルドカードは、部分的な単語または語句の末尾でのみ使用できます。 例については、作業項目クエリの例および [履歴] フィールドを使用した作業項目のクエリに関する記事をご覧ください。
Note
すべてのデプロイでフルテキスト検索がサポートされているわけではありません。 たとえば、SQL Express と一部のクラウド SQL 構成では、フルテキスト検索がサポートされていません。 これらのデプロイでは、 Contains 演算子と Not Contain 演算子のみが表示されます。
Azure DevOps Serverは、基になるSQL Serverがフルテキスト インデックス作成をサポートしている場合に、フルテキスト フィールド (PlainText と HTML) と Title フィールドにフルテキスト検索のインデックスを作成します。
フルテキスト検索には、使用する言語の登録されたワードブレーカーを含む SQL コレーションも必要です。 コレクション データベースの照合順序がサポートされている言語と一致しない場合、結果が期待値と一致しない可能性があります。 このような場合は、代わりに Contains または Not Contain を使用します。
詳しくは、「フルテキスト検索のクエリと照合順序の設定」をご覧ください。
結合演算子
クエリでは 、AND ロジックを使用して複数の句を結合します。 追加の各句は、結果をさらにフィルター処理します。 例えば次が挙げられます。
-
State = Active AND Priority = Highは、アクティブで優先度の高い作業項目を返します。 -
State = Active AND State <> Closedは、クローズ済みとしてマークされているものを除くアクティブなアイテムを返します。 -
Assigned To = @Me AND State <> Doneは、自分に割り当てられた未完了の項目を返します。
かっこを使用して、直接 WIQL 構文で複雑なクエリの条件をグループ化できます。
-
(State = Active OR State = In Progress) AND Priority = Highは、アクティブまたは進行中の状態の優先度の高い項目を返します。
その他の例と WIQL 構文の詳細については、「 作業項目クエリ言語 (WIQL) の構文」を参照してください。
トラブルシューティングと一般的な間違い
| 問題 | 考えられる原因 | ソリューション |
|---|---|---|
| マクロが結果を返さない | @CurrentIteration Web ポータルでのみ機能します。REST API と CLI が空の結果を返す場合がある | スクリプトや API では、代わりに直接の日付を使用してください。 別の方法については、「 日付または現在のイテレーションによるクエリ」を参照してください。 |
| クエリ@TeamAreas予期しない結果が返される | マクロは エリアパス フィールドでのみ機能します。他のフィールドと一緒に使用しても効果はありません | エリア パス でフィルターしていることを確認してください。 代わりに Under 演算子を使用して、他のツリー パス フィールド (反復パス) を使用します。 |
| 単語演算子エラーが含まれています | クエリが 100 文字の制限を超えているか、無効なワイルドカードの配置を使用している | クエリ テキストを 100 文字以下に減らします。 ワイルドカードは、最初ではなく、用語の末尾 (たとえば、 feature*) でのみ使用します。 |
| グループ内のクエリが失敗する | グループ名の形式が正しくないか、グループが存在しない | チームには、正確な形式 `Assigned To In Group "[Project]\\Team Name"` を使用してください。 プロジェクト設定でグループ名を確認します。 |
| Ever 演算子が日付に対して動作しなかった | クエリ エディターは DateTime フィールドのWas Everをサポートしていません |
ビジュアル クエリ エディターの代わりに、直接 WIQL 構文を使用します。 詳細については、「作業項目クエリ言語 (WIQL) の構文」を参照してください。 |
| ブール型フィールド クエリで結果が返されない | WIQL クエリでは、値の大文字と小文字が区別されます |
CustomBoolField = True または CustomBoolField = False のように、大文字と小文字を正確に区別して使用してください（WIQL では T/F は大文字）。 |
マクロと変数のクエリ
クエリを動的にフィルター処理するには、次のマクロを使用します。
Note
次のマクロは、Web ポータルからのみサポートされています: @CurrentIteration、@CurrentIteration +/- n、@Follows、@MyRecentActivity、@RecentMentions、@RecentProjectActivity、@TeamAreas。 これらのマクロを含むクエリは、Visual Studio/チーム エクスプローラー、Microsoft Excel、またはMicrosoft Projectで開くと機能しません。
| マクロ | Description |
|---|---|
| [どれでも] |
作業項目の種類または状態と共に使用して、すべての種類または状態を検索します。 たとえば、 Work Item Type=[Any] は型ベースのフィルター処理を削除します。 |
| @CurrentIteration | イテレーション パスと共に使用して、現在のチーム コンテキストに基づいて現在のスプリント内の作業項目をフィルター処理します。 例については、「 日付または現在のイテレーションによるクエリ」 を参照してください。 @CurrentIteration は、Web ポータルから実行する場合にのみ機能します (REST API または一部のコピー/複製操作では機能しません)。 |
| @CurrentIteration +/- n |
イテレーション パスと共に使用して、現在のイテレーションに対するスプリントを含めます (たとえば、@CurrentIteration-1や@CurrentIteration+2)。 Azure BoardsとAzure DevOps Serverの Web ポータルでサポートされます。 |
| @Follows |
ID と In 演算子を使用して、プロジェクトでフォローする作業項目を一覧表示します。
作業項目やプルリクエストのフォローについて参照してください. このマクロは、Web ポータルからのみ機能します。 |
| @Me | ID フィールドと共に使用して、アカウントにリンクされているアイテム ( Created By=@Me など) をフィルター処理します。
「割り当て、ワークフロー、またはボードの変更によるクエリ」を参照してください。 |
| @MyRecentActivity |
ID とInを使用して、過去 30 日間に表示または更新した作業項目を一覧表示します。 同じリストの [作業項目] ページ の [マイ アクティビティ ] ピボットを参照してください。 |
| @Project |
チーム プロジェクトと共に使用して、現在のプロジェクトの作業項目 (Team Project=@Project など) をフィルター処理します。
プロジェクト間のクエリを参照してください。 |
| @RecentMentions |
ID とInを使用して、ディスカッションに記載されている作業項目を一覧表示します。 「作業項目」ページのメンションのピボットを参照してください。 |
| @RecentProjectActivity |
ID とInを使用して、プロジェクト全体で最近更新された作業項目を一覧表示します。 このマクロは、最大 5,000 個の項目を返します。実際のウィンドウはプロジェクトのアクティビティによって異なります。 |
| @StartOfDay | DateTime フィールドと共に使用して、今日を基準としてフィルター処理します (たとえば、 Closed Date>=@StartOfDay-7)。 |
| @StartOfMonth | DateTime フィールドと共に使用して、月の始まりを基準としてフィルター処理します (たとえば、 Created Date>=@StartOfMonth-3)。 |
| @StartOfWeek | DateTime フィールドと共に使用して、週の始まりを基準としてフィルター処理します (たとえば、 Changed Date>=@StartOfWeek-2)。 |
| @StartOfYear | DateTime フィールドと共に使用して、年の開始日を基準としてフィルター処理します (たとえば、 Target Date>=@StartOfYear)。 |
| @TeamAreas |
チームのエリア パスに割り当てられているアイテムを検索するには、エリア パスと = オペレーターでのみ使用します (たとえば、Area Path=@TeamAreas [Fabrikam Fiber]\Web)。 Azure BoardsとAzure DevOps Serverの Web ポータルでサポートされます。 |
| @Today | DateTime フィールドと共に使用して、今日を基準としてフィルター処理します (たとえば、 Created Date>=@Today-7)。
日付または現在のイテレーションによるクエリを参照してください。 |
一般的なマクロの例
マクロを使用してクエリを動的にする代表的なクエリ例を次に示します。
| Query | 返品 (Web ポータル) |
|---|---|
Iteration Path = @CurrentIteration |
現在のスプリントの作業項目 |
Iteration Path = @CurrentIteration-1 |
前のスプリントの作業項目 |
Assigned To = @Me |
現在のユーザーに割り当てられているアイテム |
Created Date >= @Today-30 |
過去 30 日間に作成されたアイテム |
State = Active AND Area Path = @TeamAreas [Project]\MyTeam |
チームの領域内のアクティブなアイテム |
Work Item Type = [Any] |
すべての作業項目タイプ (型のフィルター処理を削除) |
Assigned To In Group @Follows |
フォローしているユーザーに割り当てられたアイテム |
Note
@CurrentIteration、@Me、@Follows、@TeamAreasなどのマクロは、Web ポータルでのみ機能します。 REST API、CLI、およびPower BIの場合は、代わりに直接の日付とユーザー ID を使用します。 別の方法については、「 日付または現在のイテレーションによるクエリ」を参照してください。
関連コンテンツ
REST API
プログラムでクエリを操作するには、次の REST API リソースのいずれかを参照してください。