在 Azure Boards 中定義工作項目查詢

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

Visual Studio 2019 |Visual Studio 2022

工作項目查詢會根據您提供的篩選準則產生工作項目清單。 您可以儲存這些受控查詢並與他人共用。

您可以從入口網站或支援的用戶端建立查詢,例如 Visual Studio Team Explorer。 若要支援大量更新或新增,請使用 Excel 或.csv檔案匯入或匯出查詢。

您可以從入口網站或支援的用戶端建立查詢,例如 Visual Studio Team Explorer。 若要支援大量更新或新增,請使用 Excel 匯入或匯出查詢。

請參閱本文稍後的建議最佳做法。

必要條件

  • 您必須擁有 項目關係人 存取權,才能檢視及執行共用查詢。 根據預設,所有項目成員都有項目關係人存取權。 如需詳細資訊,請參閱 變更共用查詢或資料夾的許可權。
  • 您必須具有 基本 存取權或更高許可權,才能新增和儲存共享查詢。
  • 您必須將 [參與] 許可權設定為 [允許],才能將您要新增查詢的資料夾設定為 [允許 ]。 根據預設, 參與者 群組 沒有 此許可權。

注意

具有公用專案項目關係人存取權的使用者具有完整查詢功能的存取權,就像具有基本存取權的使用者一樣。 如需詳細資訊,請參閱專案關係人存取快速參考

  • 根據預設,具有 項目關係人 存取權的所有專案成員和使用者都可以檢視和執行所有共享查詢。 您可以變更共享查詢資料夾或共享查詢的許可權集。 如需詳細資訊,請參閱 設定查詢許可權
  • 若要在共用查詢下 新增和儲存查詢,您必須獲得 基本 存取權或更高許可權。 此外,您必須將 [參與] 許可權設定為 [允許 ],才能將查詢新增至該資料夾。 根據預設, 參與者 群組沒有此許可權。

選擇查詢篩選條件

從 查詢編輯器,您可以選取篩選,以跳至具有範例查詢的文章。 除了查詢篩選之外,您還可以 以互動方式將篩選套用至查詢結果

注意

受控查詢不支持鄰近搜尋,但語意搜尋確實支援。 此外,語意搜尋同時 * 支援 和 ? 作為通配符,而且您可以使用多個通配符來比對多個字元。 如需詳細資訊,請參閱 功能工作項目搜尋


篩選功能

巨集



您也可以使用 Filter 函式以互動方式篩選查詢。

開啟查詢

從網頁瀏覽器中,[1] 檢查您已選取正確的專案,[2] 選擇 [面板 > 查詢],然後選擇 [3] 選擇 [全部]。

Open Boards>Queries, vertical nav

如果這是您第一次開啟 查詢,頁面就會開啟至 [我的最愛]。 此頁面會列出您指出的查詢是我的最愛。 否則,您可以選擇 [ 全部 ] 來檢視您為專案定義和共用查詢的所有查詢。

提示

您或您的小組已選擇作為我的最愛的查詢顯示在 [ 我的最愛 ] 頁面上。 [我的最愛] 查詢和其他物件也會出現在您的 [專案 ] 頁面上。 如需詳細資訊,請參閱 設定個人或小組我的最愛

從網頁瀏覽器開啟 Boards > 查詢

From your web browser, open Boards>Queries

定義一般清單查詢

入口網站中的 [查詢 ] 索引標籤或 Team Explorer 中的 [ 工作專案 ] 索引標籤啟動新的查詢。

選取 [新增查詢]

Screenshot to Add new query, new experience.

查詢編輯器 會顯示下列預設設定:工作專案一般清單、工作項目類型=[Any]State=[Any]

Screenshot of Query Editor with flat list of work items selected.

修改 Values新增或移除子句,或將查詢類型變更[工作專案],以及將連結或導向至工作專案的樹狀結構

Screenshot to Queries page, Choose New query from the drop down menu.

查詢編輯器 會顯示下列預設設定:一般工作專案清單、Team Project=@Project(目前專案)、工作專案類型=[Any],以及 State=[Any]

Screenshot of Query Editor with flat list of work items selected.

您可以修改 Values新增或移除子句。 或者,將 查詢 類型變更為 [工作專案] 和 [直接連結 ] 或 [ 工作專案樹狀目錄]。

跨專案或項目內查詢

依預設,新的查詢會將範圍設定為目前專案。 但是,您可以建立查詢來尋找組織或專案集合中定義的工作專案。 不過,您儲存的所有查詢都會儲存在特定專案下。

若要列出兩個或多個項目中定義的工作專案,請勾選 [ 跨項目查詢]。 例如,下列查詢會尋找過去 30 天內所有專案中建立的所有功能。

Screenshot of Query Editor with Query across projects checked.

核取 [ 跨項目 查詢] 后,您可以新增 [Team Project ] 欄位以篩選至選取的項目數目。

Screenshot of Query Editor with Team Project and other fields added to filter.

注意

將多個專案名稱與清單分隔符分隔,其對應至為用戶端電腦定義的區域設定,例如逗號 ,

  • 只有在您檢查跨專案查詢之後,才能使用Team Project字段。
  • 核取 [跨項目查詢] 時,集合中所有項目中定義之所有工作項目類型的所有欄位都會出現在 [欄位] 下拉功能表中
  • 取消核取 [跨項目查詢] 時,只有來自這些工作項目類型的欄位,如目前專案中所定義,會出現在 [字段] 下拉功能表中

定義 子句

若要建立查詢,請定義一或多個子句。 每個子句都會定義單一欄位的篩選準則。

範例查詢子句

及/或 欄位 運算子
And 指派給 = @Me

如需以欄位數據類型為基礎的可用運算子清單,請參閱 查詢索引快速參考

所有子句都會新增為 And 語句。 選取 [或 ] 以變更群組。 Group 子句,以確保子句語句是在所需的序列中執行。

選取 [新增子句 ] 以在查詢結尾新增另一個子句,然後選取該子句的 FieldOperatorValue

Screenshot of Query Editor showing how to add a clause.

例如,藉由指定 [ 指派給 ] 字段、等於 (=) 運算符和 代表使用者身分識別的 @Me 宏,搜尋指派給您的所有工作專案。

提示

若要檢視查詢的WIQL語法,以及如何使用括弧來群組子句,請安裝 Marketplace Wiql 編輯器。 此延伸模組支持檢視 WIQL 語法,並將它匯出至 WIQL 檔案,以用於 REST API 呼叫。 如需詳細資訊,請參閱工作專案查詢語言的語法(WIQL)。

定義查詢子句的檢查清單

  1. 在第一個空白資料列的 [欄位] 資料列標題下,選擇向下箭號以顯示可用欄位的清單,然後選擇清單中的專案。 如需詳細資訊,請參閱 查詢欄位和值

  2. 在相同數據列的 [運算符 ] 資料行標題下,選取向下箭號以顯示可用運算符的清單,然後選擇清單中的專案。 如需詳細資訊,請參閱 運算子

  3. 在相同的數據列的 [值] 數據行標題下,輸入值,或選取向下箭號,然後選擇清單中的專案。 如需如何使用宏或變數指定目前專案、使用者、日期或其他選取範圍的詳細資訊,請參閱 變數

  4. 若要新增 子句,請選擇 [ 新增子句]。

    您可以將 子句新增至查詢結尾,或使用對應的圖示執行下列工作:

    • 插入新的篩選線
    • 拿掉此篩選行
    • 群組選取的子句
    • 取消群組子句

使用工作專案樹狀目錄來檢視階層

使用 [ 工作專案 樹狀結構] 查詢來檢視多層式的巢狀工作項目清單。 例如,您可以檢視所有待辦專案及其連結的工作。 若要將焦點放在樹狀結構的不同部分,請選擇 [全部展開] 或 [全部折疊]。

注意

您無法建構顯示測試計劃、測試套件和測試案例階層式檢視的查詢。 這些專案不會使用父子連結類型連結在一起。 不過,您可以建立列出測試相關工作專案的直接鏈接查詢。 此外, 您也可以透過 [測試計劃] 頁面檢視階層。

Screenshot of Query Results List showing a Tree Query.

Screenshot of Query Results List showing a Tree Query.

定義父工作和子工作項目的篩選準則。 若要尋找連結的子系,請先選取 [比對最上層工作專案]。 若要尋找連結的父代,請先選取 [比對連結的工作專案]。

Screenshot of Query Editor view of Tree of work items.

使用 [工作專案] 和 [ 直接連結 ] 查詢來追蹤相依於其他追蹤工作的工作專案,例如工作、Bug、問題或功能。 例如,您可以檢視相依於所實作之其他專案的待辦專案或修正的 Bug。

使用直接連結查詢來追蹤跨小組的相依性。 此查詢也可協助您管理小組所做的承諾。 選擇頂端和連結工作項目的篩選準則。 然後,選取連結類型以篩選相依性。

Screenshot of Direct Links Query Results.

Screenshot of Query Editor, Direct Links Query.

選擇下列其中一個選項,以篩選您的第一層工作專案清單:

  • 只傳回具有相符連結的專案:第一層工作專案會傳回,但只有在它們具有連結的工作專案篩選準則所指定的工作項目連結時才會傳回。
  • 傳回所有最上層專案:儘管連結的工作專案篩選準則,但所有第一層工作專案都會傳回。 如果第二層工作專案符合連結的工作專案篩選準則,則會傳回連結至第一層的工作專案。
  • 只會傳回沒有相符連結的專案:會傳回第一層工作專案,但只有在沒有連結工作專案篩選準則所指定工作項目的連結時才會傳回。

如需每個連結類型的詳細資訊,請參閱 連結類型參考

使用和/或邏輯表達式

指定 AndOr 以建立查詢子句的邏輯表達式。 使用 And 來尋找符合目前 子句和上一個子句中準則的工作專案。 使用 Or 來尋找符合目前 子句或上一個子句中準則的工作專案。

為每個工作專案欄位新增一個新子句,以精簡搜尋準則。 新增 子句,只傳回您想要的工作專案集。 如果您未收到查詢預期的結果,請加以精簡。 您可以新增、移除、群組或取消群組查詢子句,以改善查詢結果。

群組查詢子句,以與其餘查詢分開的單一單位運作。 群組子句類似於將括號放在數學方程式或邏輯語句中的表達式周圍。 當您群組子句時, And 群組中第一個子句的 或 Or 會套用至整個群組。

Group 子句

Grouped 子句會以與查詢其餘部分分開的單一單位運作。 群組子句類似於將括號放在數學方程式或邏輯表達式周圍。 群組 And 中第一個子句的 或 Or 運算子會套用至整個群組。

如下列範例所示,群組子句會轉譯為對應的邏輯表達式。

查詢 Grouped 子句 邏輯表達式
1 Screenshot showing a group clause query. Filters are set up for the Work item type field and either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type, State, and Assigned to fields. An OR operator groups the State and Assigned to fields.
2 Screenshot showing a group clause query, with filters for both the Work item type field and one of either the State field or the Assigned to field. Screenshot of a logical expression. An AND operator groups the Work item type with the State or Assigned to fields, which are grouped by an OR operator.
3 Screenshot showing a group clause query. Filters are set up for either the Work item type field or both the State field and the Assigned to field. Screenshot of a logical expression. An OR operator links the Work item type to both the State and the Assigned to fields, which are linked by an AND operator.

這些查詢會傳回類型為 Bug 並符合下列邏輯表示式的工作專案:

  • 查詢 1AND State=Active OR Assigned to @Me
  • 查詢 2AND (State=Active OR Assigned to @Me)
  • 查詢 3OR (State=Active AND Assigned to @Me)

若要將一或多個子句分組,請加以選取,然後選取 群組子句圖示。

Screenshot of Web portal, Query Editor, Group Selected Query Clauses.

您也可以將數個群組子句分組。 核取每個子句的方塊。 然後,選擇 群組子句圖示。

Screenshot of Web portal, Query Editor, Group multiple query clauses.

如果您的查詢結果未傳回預期的結果,請執行下列步驟:

  • 請確定每個子句都定義為您想要的。
  • 確認 And/Or 每個子句的指派。 如果您的結果包含比預期更多的工作專案,則子句通常會 Or 存在,而不是 And 子句。
  • 判斷您是否需要分組或變更查詢子句的群組,以及 And/Or 每個群組子句的指派。
  • 新增更多查詢子句以精簡查詢篩選準則。
  • 檢閱可用來指定 欄位、運算元和值的選項。
  • 請參閱 本文稍後的最佳做法

取消群組 子句

若要取消子句群組,請選取 群組子句的 ungroup 子句圖示。


在儀錶板中檢視查詢結果

下列兩個小工具會顯示查詢結果。 您可以直接從這些小工具開啟工作專案。

  • 指派給我的工作:列出指派給登入使用者的所有建議或作用中工作專案。 列出 [標識符]、[狀態] 和 [標題] 字段。
  • 查詢結果小工具:顯示平面、樹狀結構或直接連結查詢的結果。 您可以設定透過小工具顯示的欄位、調整資料行欄位的大小,以及展開和折疊樹狀目錄和直接連結查詢。

如需詳細資訊,請參閱 將小工具新增至儀錶板

使用父標題檢視查詢結果小工具

您可以使用顯示父標題來檢視查詢的結果。 若要這樣做,請執行下列步驟:

  1. 建立查詢,以篩選感興趣的工作專案。 查詢可以是一般清單、樹狀結構或直接鏈接查詢。
  2. 將 [ ] 欄位新增為資料行。
  3. 將查詢儲存為共用查詢或 Team 我的最愛。
  4. 查詢結果小工具 新增至儀錶板並設定查詢。 確定 [父] 欄位已設定為顯示。

下圖說明顯示父欄位的查詢結果小工具。

Screenshot of query results widget showing a Parent column field.

查詢超連結會使用類似 Transact-SQL 的工作專案查詢語言 (WIQL)。 如需詳細資訊,請參閱工作專案查詢語言的語法(WIQL)。

注意

大部分的瀏覽器會針對 URL 字串強制執行介於 2000 到 2083 個字元之間的限制。

將 URL 語法的 WIQL 部分編碼。 您可以使用任何 URL 編碼器工具來編碼您的 URL。

https://dev.azure.com/OrganizationName/ProjectName/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

例如,下列超連結會列出 FabrikamFiber/Web 區域路徑下定義之 FabrikamFiber/Web 區域路徑下所有作用中 Bug 的標識符和標題。

https://dev.azure.com/fabrikam/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.State%5D%3D'Active'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'

譯碼的 WIQL 符合:

SELECT [System.ID], [System.Title]
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug'
   AND [System.State]='Active'
   AND [System.AreaPath]='FabrikamFiber\Web'

注意

Azure Boards 查詢的 WIQL 長度不得超過 32K 個字元。

https://{ServerName}/{CollectionName}/{ProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage}

例如,下列超連結會列出 FabrikamFiber/Web 區域路徑下所有 Bug 的標識碼、標題和狀態。

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=SELECT%20%5BSystem.ID%5D%2C%20%5BSystem.Title%5D%2C%20%5BSystem.State%5D%20FROM%20WorkItems%20WHERE%20%5BSystem.TeamProject%5D%3D'FabrikamFiber'%20AND%20%5BSystem.WorkItemType%5D%3D'Bug'%20AND%20%5BSystem.AreaPath%5D%3D'FabrikamFiber%5CWeb'%20%20

例如,請參閱下列非編碼專案。

http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql=
SELECT [System.ID], [System.Title], [System.State] 
   FROM WorkItems 
   WHERE [System.TeamProject]='FabrikamFiber' 
   AND [System.WorkItemType]='Bug' 
   AND [System.AreaPath]='FabrikamFiber\Web'   

最佳作法

下列最佳做法適用於您可以建立的下列查詢:

建立專注的選擇性查詢

套用查詢所需的所有篩選條件,以定義高度選擇性的查詢。 查詢越有選擇性,結果集越小。 結果集越小,查詢的目標就越高,而且有選擇性。

使用標籤來分類工作專案

使用 工作項目標記 來分類工作專案,而不是自定義欄位。 篩選標籤標的查詢通常會比篩選字串相符項目的查詢執行得更快。

不同於自定義欄位比對或部分相符專案,具有 Tags Contains 作業的查詢不需要完整掃描所有工作項目數據表。

用於 Contains words 字串比對

若要篩選字串比對,請使用 Contains Words 而非 Contains 運算符。 運算子 Contains Words 會在指定的欄位上執行全文搜索,這通常會更快速地完成。

Contains運算符會執行數據表掃描,這是比 Contains Words 運算子慢的作業。 它也會耗用更多的CPU週期。 這些 CPU 週期可能會導致您遇到速率限制。 如需詳細資訊,請參閱 速率和使用量限制

使用 In Group 運算子指定小型群組

運算子 In Group 會根據值群組內的相符項目來篩選工作專案。 值群組會對應至小組、安全組或 工作追蹤類別中包含的值。 例如,您可以建立查詢來尋找指派給小組任何成員的所有工作專案。 或者,尋找屬於需求類別 (Microsoft.RequirementCategory) 的所有工作專案。

當您篩選包含大量成員的群組時,結果集通常會較大且不選取。 此外,如果群組對應至大型 Microsoft Entra 群組,查詢會產生相當大的成本,以從 Microsoft Entra ID 解析該群組。

避免使用否定運算符

否定運算元,例如 <>, Not In, Not Under, Not In Group,通常會產生非選取查詢和大型結果集。

只在必要時使用負號運算符。 請一律先嘗試尋找替代方案。 例如,如果 Field1 具有 AB、CD,請指定 Field1 In A, B, C 子句,而不是否定子Field1 <> D句。

避免字串比較

包含字串比較的查詢會產生原本效率不佳的數據表掃描。 相反地,我們建議您使用標記或特定的自定義字段做為替代方案,特別是在查詢執行不佳時。

限制 Or 運算子

限制查詢中定義的運算子數目 Or 。 使用較少的 Or 運算符時,查詢的執行效能會更好。 太多 Or 運算子會使查詢無法選取。 如果您的查詢執行速度緩慢,請將 Or operator 子句重新排序到查詢子句頂端。

儲存查詢

由於內部優化,已儲存的查詢通常會在未儲存的查詢上執行得更好。 當您打算重複使用查詢時,請一律儲存查詢。 即使是透過 REST API 執行的 WIQL 查詢,也會透過入口網站儲存 WIQL 來呼叫 REST API,因此它們較不容易未來效能回歸。

執行查詢

有時候您需要執行查詢數次,才能達到正確的優化計劃。 請務必儲存查詢,並在 30 分鐘的期間內執行最多 10 次。 如此一來,系統就可以檢查並尋找最適合您查詢的優化計劃。