查詢欄位、運算子和巨集

Azure DevOps 服務 |Azure DevOps Server |Azure DevOps Server 2022

提示

第一次投稿嗎？ 從 「定義 程序步驟的查詢」或「 查詢快速參考 」作為範例開始。

在 查詢編輯器 建立查詢時，請使用這份參考指南查詢欄位資料型別、查詢運算子、巨集和變數。 所有運算子和巨集在 Azure Boards 中都被支援;有些僅適用於特定的 Azure DevOps Server 版本。

如需快速範例和編輯器工作，請參閱 查詢快速參考 和 管理和組織查詢。

先決條件

類別 要求
專案成員資格 您必須成為專案 成員 。
存取層級 - 查看並執行共享查詢：您必須是 Project 成員。
- 新增與儲存共用查詢：您必須至少擁有 Basic 存取權限。
權限 確保您要新增查詢的資料夾之 貢獻 權限已設為 允許。 你的組織可能需要手動設定貢獻 者 群組來授予此權限。

注意

你需要同時具備足夠的存取權限和 貢獻 權限才能儲存共享查詢。 基本的存取權是不夠的。

類別 要求
專案成員資格 您必須成為專案 成員 。
存取層級 - 查看並執行共享查詢：您必須是 Project 成員。
- 新增與儲存共用查詢：您必須至少擁有 Basic 存取權限。
權限 確保您要新增查詢的資料夾之 貢獻 權限已設為 允許。 你的組織可能需要手動設定貢獻 者 群組來授予此權限。

注意

你需要同時具備足夠的存取權限和 貢獻 權限才能儲存共享查詢。 基本的存取權是不夠的。

查詢欄位數據類型和值

指定一個與欄位資料型態相符的值。 下表列出支援的資料型態：

注意

對於Azure Boards（雲端），資料型態與 Process > 欄位頁面 上的欄位相符。 對於內部部署，資料類型會與定義上的type屬性對應。 如需詳細資訊，請參閱 工作專案欄位和欄位屬性。

資料類型 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 儲存格式化文字，如 描述 或 重製步驟。 當全文檢索搜尋可用時，會為這些欄位編製索引。 若要查詢 RTF 欄位，請參閱 依標題、標識碼和 RTF 字段查詢。
身分識別 儲存識別使用者身分的簡短文字字串。
整數 儲存一個有符號的 32 位元整數，例如 0、1、2 或 34。
純文字 或 文字欄位（多行） 儲存長文字值，例如 應用程式開始資訊。 這些欄位在支援的情況下會被編入全文檢索索引。 請參閱 依標題、ID 和 RTF 欄位查詢。
picklistDouble 包含小數值選擇清單的自訂欄位。
picklistInteger 自訂欄位，儲存整數值的選擇清單。
picklistString 包含簡短文字值 （255 個字元或更少） 的挑選清單的自訂欄位。
字串 或 文字欄位 （單行） 儲存最多 255 個 Unicode 字元的短文字。 團隊經常將這些欄位用於選項清單或下拉式功能表。
TreePath 代表分支樹，例如區域路徑或迭代路徑。 選擇有效的節點值。 你可以篩選平等、不平等、「低於」或「不低於」。使用 In and Not In 運算子來指定多個值。 為專案定義樹狀結構—— 區域路徑 與 迭代路徑 ——並選擇要與團隊關聯的節點。 如需查詢範例，請參閱 依區域或反覆專案路徑查詢 和 依日期或目前反覆專案查詢。

注意

這些 picklist... 類型僅適用於為繼承程序定義的自訂欄位。

日期和時間模式

您針對 DateTime 字段輸入的日期和時間模式應該符合您透過設定檔選取的日期與時間模式。 若要檢視或變更您的選取範圍，請參閱 設定用戶喜好設定。

顯示 [時間和地區設定] 窗格上 [日期模式] 下拉式清單選項的螢幕快照。 顯示 [時間與地區設定] 窗格上 [時間模式] 下拉式清單選項的螢幕快照。

顯示 [時間] 和 [地區設定] 窗格的螢幕快照，其中包含 [日期模式] 和 [時間模式] 字段。

查詢運算子

使用運算子來定義子句中的值必須如何與工作項目的欄位的值相關。 如需欄位資料類型，請參閱 工作專案欄位參考。 如需建置查詢的協助，請參閱 定義查詢。

查詢運算子 當運算子傳回相符的工作專案時 適用的數據類型
= 符合條件值。 數字 （double/decimal/GUID/Integer）、字串、DateTime、TreePath
<> 不符合條件值。 數字、字串、日期時間、樹狀路徑
> 大於子句值。 數字、字串、日期時間
< 價值小於該條件值。 數字、字串、日期時間
>= 大於或等於條件值。 數字、字串、日期時間
<= 小於或等於子句值。 數字、字串、日期時間
=[欄位] 符合另一個指定欄位中的值 （必須是相同的資料類型）。 相同資料類型的欄位名稱 （布林值欄位會比較相等性與其他欄位）。
<>[欄位] 與另一個指定欄位中的值不符。 相同資料類型的欄位名稱。
>[欄位] 大於另一個指定欄位中的值。 相同資料類型的欄位名稱。
<[欄位] 小於另一個指定欄位中的值。 相同資料類型的欄位名稱。
>=[欄位] 大於或等於另一個指定欄位中的值。 相同資料類型的欄位名稱。
<=[欄位] 小於或等於另一個指定欄位中的值。 相同資料類型的欄位名稱。
Contains 包含完全或部分文字相符。 繩子
不包含 不包含精確或部分文字匹配。 繩子
包含單詞 可以匹配精確的片語或單字（支援使用尾端通配符 *）。 限制：100 個字元。 此運算子使用全文檢索索引;如需伺服器和定序需求，請參閱本文中的全文檢索區段。 為全文檢索建立索引的長文字欄位（純文字、HTML、歷史和標題）。
不包含單字 排除包含指定片語或單字的項目。 限制：100 個字元。 在配套子句中使用 with Contains Words 來包含或排除關鍵字。 編製索引的文字字段，用於全文檢索。
在 符合分隔集中的任何值 （使用您的 OS 區域清單分隔符號，通常是逗號）。 數字、字串、日期時間、樹狀路徑
為空白 比對 HTML 欄位不包含任何內容 （未指定值） 的項目。 支援 Azure Boards 及 Azure DevOps Server。 HTML
不是空的 比對 HTML 欄位包含內容的項目。 支援 Azure Boards 及 Azure DevOps Server。 HTML
不在 排除在一組以分隔符號隔開的值中（使用區域清單分隔符號）。 支援 Azure Boards 及 Azure DevOps Server。 數字、字串、日期時間、樹狀路徑
在群組中 比對具名群組 （小組、安全性群組或類別） 成員的值。 例如，使用 [參與者] 群組或模式 [Project Name]\Team Name中命名的小組群組。 如需範例，請參閱 依指派或工作流程變更查詢 。 僅將 [ 在群組中 ] 與字串類型欄位或工作專案類型搭配使用。 當您的帳戶使用 Microsoft Entra ID 時，您可以使用 Microsoft Entra ID 群組，或本地端使用 Active Directory 群組。 字串 （符合群組或小組名稱） 或工作專案類型
不在群組中 排除具名群組的成員。 符合使用者群組或專案類別的字串。
不在底下 排除等於或包含在指定樹狀結構節點下的項目。 TreePath
下 比對等於或包含在指定樹節點下的項目。 TreePath
曾經 符合欄位在過去某段時間所保留的值。 （查詢編輯器：僅支援字串欄位。DateTime 需透過直接 WIQL 查詢才支援。） 字串、日期時間

提示

您可以針對其他資料類型（例如反覆項目路徑）使用運算子（例如 Was Ever）建構 WIQL 查詢。 如需範例，請參閱 列出從短期衝刺移出的工作專案。

常見運算子範例

以下是使用各種運算子的代表性查詢範例：

Query Returns
State = Active 工作項目狀態為「Active」
Priority <> Low 除低優先順序項目外的所有項目
Created Date >= @Today-7 過去7天內產生的工作項目
Assigned To = @Me 分配給目前使用者的項目
Tags Contains "frontend" 標籤包含「frontend」的項目
State In (Active, In Progress) 任一狀態中的項目
Area Path Under "Project\Web" 網路區域內的所有項目，包括子區域
Assigned To In Group "[Project]\Developers" 分配給開發團隊成員的物品
Description Contains Words "urgent" 描述中包含「緊急」一詞的項目

全文檢索和部分單字搜尋

使用 Contains 或 Does Not Contain，以在長文字欄位中搜尋完全或部分相符的內容。 這些運算元使用查詢索引。 使用 包含字詞 或 不包含字詞 來搜尋完全相符的詞組，或使用尾端萬用字元 (*)。 這些運算元需要全文索引。

您只能在部分單字或片語的結尾使用萬用字元。 如需範例，請參閱工作項目查詢範例和使用 [歷程記錄] 欄位來查詢工作項目。

注意

並非所有部署都支援全文檢索搜尋。 例如，SQL Express 和某些雲端 SQL 設定不支援全文檢索搜尋。 在這些部署中，只有 Contains 和 Does Not Contain 運算子可見。

當底層 SQL Server 支援全文索引時，Azure DevOps Server 會索引長文欄位（純文字與 HTML）及標題欄位以進行全文搜尋。

全文檢索搜尋也需要 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）語法。

故障排除與常見錯誤

Problem 可能原因 Solution
宏觀分析沒有結果 @CurrentIteration 僅能在網頁入口中運作;REST API 和 CLI 可能會回傳空的結果 在指令碼或 API 中，請改用明確日期。 關於替代方案，請參見 「依日期查詢」或「目前迭代」。
@TeamAreas查詢會回傳意料之外的結果 巨集只支援 區域路徑 欄位;與其他欄位一起使用則沒有影響 確認你正在 Area Path 上篩選。 改用其他樹狀路徑欄位（迭代路徑），並改搭配 位於下層 運算子。
包含文字運算子錯誤 查詢超過 100 字元限制或使用無效的萬用字元位置 將查詢文字縮減至100字以下。 萬用字元只能用在詞尾（例如 feature*），不能用在開頭。
在群組中查詢失敗 群組名稱格式錯誤或群組不存在 請使用確切格式：Assigned To In Group "[Project]\\Team Name"，用於團隊。 在專案設定中確認群組名稱。
有一天接線員沒在約會時間工作嗎 查詢編輯器不支援在 DateTime 欄位上使用 Was Ever 使用直接的 WIQL 語法，而非視覺化查詢編輯器。 如需詳細資訊，請參閱工作專案查詢語言的語法（WIQL）。
布林欄位查詢未回傳任何結果 在 WIQL 查詢中，值會區分大小寫 使用完全相同的情況： CustomBoolField = True 或 CustomBoolField = False （WIQL 中大寫的 T/F）。

查詢巨集和變數

使用下列巨集來動態篩選查詢。

注意

只有 Web 入口網站支援下列巨集：@CurrentIteration、@CurrentIteration +/- n、@Follows、@MyRecentActivity、@RecentMentions、@RecentProjectActivity 和 @TeamAreas。 包含這些巨集的查詢在 Visual Studio/Team Explorer、Microsoft Excel 或 Microsoft Project 中開啟時無法正常運作。

巨集 Description
[任何] 搭配 工作專案類型 或 狀態 使用，以搜尋所有類型或狀態。 例如， Work Item Type=[Any] 移除以類型為基礎的篩選。
@CurrentIteration 可搭配 迭代路徑 使用，根據目前的團隊環境篩選目前衝刺中的工作項目。 如需範例，請參閱依日期或目前的迭代查詢。 @CurrentIteration 只有在從入口網站執行時才有效（不適用於REST API或某些複製/複製作業）。
@CurrentIteration +/- n 搭配 疊代路徑 使用，以包含相對於目前疊代的衝刺（例如 @CurrentIteration-1 或 @CurrentIteration+2）。 喺 Azure Boards 同 Azure DevOps Server 嘅 web portal 中得到支持
@Follows 搭配 識別碼 和 In 運算子使用，以列出您在專案中追蹤的工作項目。 請參閱 追蹤工作專案或拉取請求。 此巨集只能從網頁入口運作。
@Me 搭配身分欄位使用，以篩選連結至您帳戶的項目 （例如 Created By=@Me）。 請參閱 依指派、工作流程或面板變更查詢。
@MyRecentActivity 搭配 識別碼 和 In 使用，以列出您在過去大約 30 天內檢視或更新的工作項目。 請參閱 [工作專案] 頁面的 我的活動 樞紐檢視，來查看相同的清單。
@Project 搭配 Team 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 portal 中得到支持
@Today 搭配 DateTime 欄位使用，以相對於今天進行篩選 （例如 Created Date>=@Today-7）。 請參閱 依日期或目前迭代查詢。

常見的巨集範例

以下是使用巨集使查詢動態的代表性查詢範例：

Query Returns（網路入口網站）
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 指派給你追蹤的對象的項目

注意

像 @CurrentIteration、@Me、@Follows 和 @TeamAreas 這類巨集僅能在 Web 入口網站中使用。 對於 REST API、CLI 和 Power BI，改用直接日期和使用者 ID。 關於替代方案，請參見 「依日期查詢」或「目前迭代」。

相關內容

REST API

若要以程式設計方式與查詢互動，請參閱下列其中一個 REST API 資源：

  • 上次更新時間：