工作項目查詢語言 (WIQL) 語法參考

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

您可以使用 WIQL 語法將查詢定義為超連結，或使用工作專案查詢語言（REST API）時。

WIQL 支援透過入口網站查詢編輯器提供的所有功能，以及其他一些功能。您可以指定要傳回的欄位，以及查詢子句的邏輯分組。您也可以使用 ASOF 子句，根據截至前一個日期的指派進行篩選。

Important

WIQL 語法可用來執行 Wiql REST API 查詢。 API 只會傳回工作專案識別碼，無論您在陳述式中 SELECT 包含哪些欄位。若要取得完整資訊，請（1）從 WIQL 取得標識碼，然後（2）透過依標識碼和特定欄位取得工作專案清單來取得工作專案。

Prerequisites

Category	Requirements
Permissions	檢視工作專案或檢視此節點中的工作專案許可權設定為 [允許 ]。這些權限通常會授與每個小組專案的 [讀者] 和 [參與者] 群組成員。如需詳細資訊，請參閱許可權和群組。

查詢語言概觀

WIQL 有五個部分，如下列語法程式碼片段所示，並如表格所述。 WIQL 語法不區分大小寫。

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2025'

Tip

藉由安裝 Wiql 編輯器 Marketplace 延伸模組，您可以使用查詢編輯器建構查詢，並檢視 WIQL 語法。然後，您可以複製和修改 WIQL 語法，並使用新增至 Boards 的 Wiql Playground 中樞來執行查詢。

條	範例/描述
`SELECT`	識別要針對每個工作專案傳回的欄位。您可以指定易記名稱或參考名稱。如果名稱包含空白或句點，請使用方括號（`[]`）。
`FROM`	指出您想要查詢尋找工作專案或工作專案之間的連結。 - 用 `FROM WorkItems` 來傳回工作專案。 - 用 `FROM workItemLinks` 來傳回工作專案之間的鏈結。如需詳細資訊，請參閱查詢工作專案之間的連結。
`WHERE`	指定查詢的篩選準則。如需詳細資訊，請參閱篩選條件（`WHERE`）。
`ORDER BY`	指定傳回之工作專案的排序順序。您可以為一或多個欄位指定遞增（`Asc`）或遞減（`Desc`）。例如：`ORDER BY [State] Asc, [Changed Date] Desc`
`ASOF`	指定要套用篩選的日期，以指定歷程記錄查詢。例如，此查詢會傳回 2025 年 2 月 11 日定義為作用中的所有使用者劇本。根據日期和時間模式中提供的指引來指定日期。 `ASOF '02-11-2025'`

Note

針對 Azure Boards 進行的 WIQL 查詢不得超過 32-K 字元。系統不允許您建立或執行超過該長度的查詢。

日期和時間模式

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

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

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

比較中使用的引號（支援單引號或雙引號） DateTime 常值。它們必須採用執行查詢之本機用戶端電腦的 .NET DateTime 格式。除非指定時區， DateTime 否則常值會位於本機電腦的時區中。

WHERE 
   AND [System.ChangedDate] >= '01-18-2025 GMT'
   AND ([Closed Date] < '01-09-2025 GMT'
   OR [Resolved Date] >= '01-18-2025 14:30:01')

當在文字中 DateTime 省略時間且 dayPrecision 參數等於 false 時，會假設時間為零（午夜）。參數 dayPrecision 的預設設定為 false。

或者，您可以指定 ISO 8601 格式，無論地區設定為何，該格式都有效。 ISO 8601 以年份開頭，然後是月、日、小時、分、秒和毫秒來表示日期和時間。例如， 2025-12-10 15:00:00.000 代表當地時間 2025 年 12 月 10 日下午 3 點。使用 ISO 8601 格式的範例如下：

WHERE 
   AND [System.ChangedDate] >= '2025-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2025-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2025-01-18T00:00:00.0000000')

自訂欄位

您可以將自訂欄位新增至查詢子句。使用WIQL時，您必須指定自訂欄位的參考名稱。對於使用繼承程序模型的專案，自訂欄位通常會在其名稱前面加上 Custom. 標籤，並移除空格。例如：

友善名稱	參考名稱
`Approver`	`Custom.Approver`
`Request Type`	`Custom.RequestType`
`Scope Estimate`	`Custom.CustomEstimate`

對於使用內部部署 XML 程式模型的專案，參考名稱會由 XML 工作專案類型定義所定義。

如需詳細資訊，請參閱工作專案欄位和屬性。

指定篩選子句（`WHERE`）

子 WHERE 句會指定篩選準則。查詢只會傳回符合指定準則的工作專案。例如，下列範例 WHERE 子句會傳回作用中且指派給您的用戶劇本。

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

您可以控制邏輯運算子的評估順序，方法是將邏輯運算符括在括弧內以將篩選準則分組。例如，若要傳回指派給您或您關閉的工作專案，請使用下列範例。

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

篩選條件

每個篩選條件是由三個部分所組成，每個部分都必須符合下列規則：

欄位：您可以指定參考名稱或易記名稱。下列範例是有效的 WIQL 語法：
- 參考名稱： SELECT [System.AssignedTo] ...
- 具有空白的易記名稱： SELECT [Assigned To] ...
- 不含空白的名稱不需要方括弧： SELECT ID, Title ...
運算子：有效值會在本文稍後的運算子區段中指定。
欄位值：您可以根據指定的欄位指定下列三個值之一。
- 常值必須符合欄位值的資料類型。
- 表示特定值的變數或巨集。例如， @Me 指出執行查詢的人員。如需詳細資訊，請參閱巨集和變數。
- 另一個欄位的名稱。例如，您可以使用 [Assigned to] = [Changed by] 來尋找指派給最近變更工作項目的人員的工作專案。

如需所有系統定義欄位的描述和參考名稱，請參閱工作專案欄位索引。

Operators

查詢會使用邏輯表達式來限定結果集。這些邏輯運算式由一或多個連體作業組成。

一些簡單的查詢操作如下：

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

下表摘要說明不同欄位類型支援的所有運算子。如需每個欄位類型的詳細資訊，請參閱工作專案欄位和屬性。

=、 <>><>=和<=運算子會如預期般運作。例如， System.ID > 100 查詢大 ID 於 100 的所有工作專案。 System.ChangedDate > '01-01-25 12:00:00' 所有工作專案的查詢在 2025 年 1 月 1 日中午之後變更。

除了這些基本運算子之外，還有某些特定欄位類型特有的行為和運算元。

Note

可供您使用的操作員取決於您的平臺和版本。如需詳細資訊，請參閱查詢快速參考。

欄位類型	支援的運算子
`Boolean`	`= , <> , =[Field] , <>[Field]`
`DateTime`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever`
`Double`、`GUID`、`Integer`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever`
`Identity`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever`
`PlainText`	`Contains Words, Not Contains Words, Is Empty, Is Not Empty`
`String`	`= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever`
`TreePath`	`=, <>, In, Not In, Under, Not Under`

邏輯分組

您可以使用詞彙 AND 和 OR 一般布爾值來評估兩個子句。您可以在指定AND EVER運算子時使用字詞OR EVERWAS EVER與。您可以視需要將邏輯表達式分組並進一步聯結。以下範例示範。

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

您可以使用來否定 contains、 under和in運算子。not 您無法否定 ever 運算子。下列範例會查詢未在的 Fabrikam Fiber\Account Management子樹狀結構下指派的所有工作專案。

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

範例查詢已指派給

下列查詢編輯器範例會尋找曾經指派給 Jamal Hartnett 的所有工作專案。

已指派一般清單查詢查詢編輯器螢幕快照。

對應的 WIQL 語法如下：

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

巨集或變數

下表列出您可以在WIQL查詢中使用的巨集或變數。

Macro	Usage
`@Me`	使用此變數，在包含用戶別名的欄位中自動搜尋目前使用者的別名。例如，如果您將直欄設為 `Field`，將直欄設為 `Activated By`，`Operator`並將直欄設`=`為 `Value`，`@Me`則可以尋找您開啟的工作項目。
`@CurrentIteration`	使用此變數，根據選取的小組內容，自動篩選指派給所選小組目前短期衝刺的工作專案。
`@Project`	使用此變數來搜尋目前專案中的工作專案。例如，如果您將`Field`資料行設定為 `Team Project`，將資料行設定為，`Operator`並將資料行`=Value`設定為，`@Project`則可以找到目前專案中的所有工作專案。
`@StartOfDay` `@StartOfWeek` `@StartOfMonth` `@StartOfYear`	使用這些巨集，根據目前日、週、月、年的開始，或偏移至其中一個值來篩選 `DateTime` 欄位。例如，如果您將欄設`Field`為 `Created Date`，將直欄設為，`Operator`並將直欄`>=`設為 `Value`，`@StartOfMonth - 3`則可以尋找過去三個月內建立的所有項目。
`@Today`	使用此變數來搜尋與目前日期或更早日期相關的工作專案。您也可以透過減去天數來修改 `@Today` 變數。例如，如果您將欄設`Field`為 `Activated Date`，將欄設為 `Operator`，`>=`並將直欄設為 `Value`，`@Today - 7`則可以找到上週啟用的所有項目。
`[Any]`	使用此變數來搜尋與特定欄位所定義之任何值相關的工作專案。

`@me` 巨集

@me巨集會取代執行查詢之使用者的 Windows 整合帳戶名稱。下列範例示範如何使用巨集和對等的靜態陳述式。巨集適用於與身分識別欄位搭配使用，例如 Assigned To。

WHERE  
   [System.AssignedTo] = @Me

`@today` 巨集

您可以將巨集與任何@today欄位搭配使用DateTime。此巨集會取代執行查詢之本機電腦上的目前日期午夜。您也可以分別指定@today+x或使用 @today-y x @today天后@today和 y 天前的整數位移。使用 @today 巨集的查詢可以傳回不同的結果集，視其執行的時區而定。

下列範例假設今天是 2025 年 1 月 3 日。

WHERE  
   [System.CreatedDate] = @today

相當於：

WHERE  
   [System.CreatedDate] = '01-03-2025'

And

WHERE  
   [System.CreatedDate] > @today-2

相當於：

WHERE  
   [System.CreatedDate] > '01-01-2025'

`@StartOfDay`、、`@StartOfWeek@StartOfMonth`、`@StartOfYear`巨集

您可以將巨集與任何@StartOf...欄位搭配使用DateTime。此巨集會取代執行查詢之本機電腦上的目前日午夜、周開始、月開始或年初。

這些巨集接受格式為的 (+/-)nn(y|M|w|d|h|m)修飾詞字串。與 @Today 巨集類似，您可以指定加號或減號整數位移。如果省略時間單位限定符，則會預設為函式的自然期間。例如，@StartOfWeek("+1") 與 @StartOfWeek("+1w") 相同。如果省略加/減號（+/-）符號，則會假設加號。

此語法可讓您巢狀修飾詞並位移查詢兩次。例如，子句 Closed Date >= @StartOfYear - 1 會篩選自去年以來關閉的工作專案。當您將它修改為 Closed Date >= @StartOfYear('+3M') - 1時，它會排除去年前三個月內關閉的工作專案。下列 WIQL 語法示範：

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

下列範例假設今天是 2025 年 4 月 5 日。

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

相當於：

WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2025'

And

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

相當於：

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2025'

自訂巨集

WIQL 也支援任意自定義巨集。前面加上 @ 的任何字串都會被視為自訂巨集，並取代。自訂巨集的取代值是從物件模型中查詢方法的內容參數擷取。下列方法是用於巨集的 API：

public WorkItemCollection Query(string wiql, IDictionary context)

內容參數包含巨集的索引鍵/值組。例如，如果內容包含（project， MyProject） @project 的索引鍵值組，則會在 WIQL 中取代。MyProject 此取代是工作專案查詢產生器在 Visual Studio 中處理 @project 巨集的方式。

指定歷程記錄查詢（`ASOF`）

您可以在查詢中使用 ASOF 子句來篩選符合指定篩選條件的工作專案，因為它們是在特定日期和時間定義。

Note

您無法在 Visual Studio 的查詢產生器中建立 ASOF 查詢。如果您建立包含.wiq子句的查詢檔案（ASOF），然後在 Visual Studio 中載入該子句，則會忽略子ASOF句。

假設工作專案在 5 年 05 月 2025 日之前分類為 of Iteration PathFabrikam Fiber\Release 1 並指派給 'Jamal Hartnett'。不過，工作專案最近已指派給「Raisa Pokrovskaya」，並移至第 2 版的新反覆項目路徑。下列範例查詢會傳回指派給 Jamal Hartnett 的工作專案，因為查詢是以過去日期和時間的工作專案狀態為基礎。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2025 00:00:00.0000000'

Note

如果未指定時間，WIQL 會使用午夜。如果未指定時區，WIQL 會使用本機用戶端計算機的時區。

設定排序順序（`ORDER BY`）

您可以使用 ORDER BY 子句，依遞增或遞減順序依一或多個字段排序查詢的結果。

Note

數據層上 SQL Server 的排序喜好設定會決定預設的排序順序。不過，您可以使用 asc 或 desc 參數來選擇明確的排序順序。

下列範例會先依遞增順序排序工作 Priority 專案（預設），然後依序 Created Date 遞減順序排序（DESC）。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

查詢工作項目之間的連結

若要傳回工作項目之間的鏈結，請指定 FROM WorkItemLinks。子句中的 WHERE 篩選條件可能會套用至連結，或是連結來源或目標的任何工作專案。下列範例會傳回及其作用中子專案之間的 Product Backlog Items 連結。

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
MODE (Recursive)

下表摘要說明工作項目查詢與工作專案之間連結的查詢之間的差異。

條	工作項目	工作專案之間的連結
`FROM`	`FROM WorkItems`	`FROM WorkItemLinks`
`WHERE`	`[FieldName] = Value`	指定下列一或多個項目： `[Source].[FieldName] = Value` `[Target].[FieldName] = Value` `[System.Links.LinkType] = 'LinkName'`
`MODE`	不適用	請指定下列其中一個選項： - `MODE (MustContain)`：（預設）僅 `WorkItemLinkInfo` 傳回全部符合來源、目標和連結條件的記錄。 - `MODE (MayContain)`：傳回 `WorkItemLinkInfo` 符合來源和連結準則之所有工作項目的記錄，即使沒有連結的工作項目符合目標準則也一樣。 - `MODE (DoesNotContain)`：只有在沒有連結的工作專案符合連結和目標準則時，才會傳回 `WorkItemLinkInfo` 符合來源之所有工作專案的記錄。 - `MODE (Recursive)`：用於樹狀結構查詢（`[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'`）。鏈接類型必須是樹狀結構拓撲和向前方向。傳回符合來源之所有工作專案的記錄，以遞迴方式傳回 `WorkItemLinkInfo` 目標。 `ORDER BY` 和 `ASOF` 與樹狀查詢不相容。
`RETURNS`	`WorkItemQueryResult`	`WorkItemLink`

您可以指定下列其中一個系統連結類型名稱。

您可以指定下列其中一個系統鏈結類型名稱，或使用內部部署 XML 程序定義的自訂鏈結類型。

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward （CMMI 程式）

如需詳細資訊，請參閱連結類型參考。

樹狀結構類型查詢範例

Note

ORDER BY 和 ASOF 與樹狀查詢不相容。請勿在樹狀結構查詢中包含這些子句。

下列查詢會傳回目前專案中定義的所有工作專案類型。查詢編輯器會顯示查詢，如下圖所示。

查詢編輯器、樹狀結構查詢、所有工作項目和狀態的螢幕快照。

對等的 WIQL 語法如下：

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

直接鏈接查詢範例

下列範例會傳回目前專案中定義的所有工作專案類型。查詢編輯器會顯示查詢，如下圖所示。

查詢編輯器、直接鏈接查詢、所有工作項目和狀態的螢幕快照。

對等的 WIQL 語法如下：

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

條	Example
`AND`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`OR`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND ([System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>OR [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>')`
`NOT`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'`
`EVER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'`
`UNDER`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>AND [System.AreaPath] UNDER 'Agile1\Area 0'`
`ORDER BY`	`SELECT [System.Id], [System.Title]<br>FROM WorkItems<br>WHERE [System.TeamProject] = @project<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ORDER BY [System.Id] [asc \| desc]`
`ASOF` （時間篩選）	`SELECT [System.Title]<br>FROM workitems<br>WHERE [System.IterationPath] = 'MyProject\Beta'<br>AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'<br>ASOF '3/16/25 12:30'`

使用 Copilot 撰寫、修正和最佳化 WIQL

您可以使用 AI 助理（例如 GitHub Copilot 或其他副手）來協助建立、更正或最佳化 WIQL 查詢。將 Copilot 視為生產力輔助工具，而不是權威來源，並始終在針對生產資料執行任何產生的查詢之前檢閱和測試它。

指引和最佳實踐：

功能：Copilot 可以將純語言需求翻譯成 WIQL、修正語法錯誤（不相符的括號、缺少逗號、不正確的關鍵字）、在易記名稱和參考名稱之間轉換 SELECT 清單、產生 ASOF 子句或日期常值，以及建議子句重寫以縮小或擴大結果集。
驗證：一律在查詢編輯器或安全測試專案中驗證產生的 WIQL。使用前請檢查巨集（例如 @Me， @Today）和與地區設定相關的日期格式。
安全性：切勿將秘密、存取權杖或任何私人連接字串貼到提示中。移除或編輯您提供給 Copilot 的範例中的任何敏感值。
效能：要求 Copilot 將結果承載降到最低（只傳回必要的欄位）、新增適當的 WHERE 篩選器，以及避免過於廣泛地使用 IN 或無限制 LIKE 的搜尋。請記住 WIQL 查詢的 32 K 字元限制。
檢閱邊緣案例：確認歷史（ASOF）查詢、樹狀結構/連結查詢（FROM workItemLinks）和 WAS EVER/EVER 掃描修訂的運算子的行為，這些可能更複雜，可能需要手動調整。

範例 — 從簡單的英文產生 WIQL：

提示：「傳回專案 'Fabrikam' 中指派給 @Me 作用中 Bug 並在過去 30 天內修改的識別碼和標題。依 ChangedDate desc 排序。」

Copilot 產生：

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

使用 REST API 和 AI 自動化 WIQL 查詢

您可以使用 AI 助理（例如 Copilot）來自動化兩步驟 WIQL REST API 程式：

使用 [依 Wiql 查詢] REST API 來擷取符合 WIQL 的工作專案標識碼。
使用 [取得工作專案 API ] 來擷取這些標識碼的完整詳細數據。

人工智慧可以幫助您：

從純語言產生 WIQL，然後在程式碼中鏈結兩個 API 呼叫（例如 Python、PowerShell 或 JavaScript）。
格式化和摘要儀表板或報告的結果。

Tip

如需 REST API 詳細資料，請參閱依 Wiql 查詢（REST API）。

範例：使用 Python 和 AI 自動化 WIQL

假設您想要列出專案中所有作用中錯誤的標題和狀態。

提示副駕駛：
「撰寫使用 Azure DevOps REST API 的 Python 程式碼，以列出專案中所有作用中 Bug 的標題和狀態。使用 WIQL 取得 ID，然後擷取這些 ID 的詳細資料。」

您可以使用 Copilot 產生如下程式碼：

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-08

共用方式為

工作項目查詢語言 (WIQL) 語法參考

Prerequisites

查詢語言概觀

日期和時間模式

自訂欄位

指定篩選子句 （WHERE）

篩選條件

Operators

邏輯分組

範例查詢已指派給

巨集或變數

@me 巨集

@today 巨集

@StartOfDay、、@StartOfWeek@StartOfMonth、@StartOfYear巨集

自訂巨集

指定歷程記錄查詢 （ASOF）

設定排序順序 （ORDER BY）

查詢工作項目之間的連結

樹狀結構類型查詢範例

直接鏈接查詢範例

更多查詢範例

日期時間模式

範例子句

String 和 PlainText

面積和疊代 （TreePath）

修飾詞和特殊運算符

使用 Copilot 撰寫、修正和最佳化 WIQL

使用 REST API 和 AI 自動化 WIQL 查詢

相關內容

意見反應

其他資源

指定篩選子句（`WHERE`）

`@me` 巨集

`@today` 巨集

`@StartOfDay`、、`@StartOfWeek@StartOfMonth`、`@StartOfYear`巨集

指定歷程記錄查詢（`ASOF`）

設定排序順序（`ORDER BY`）

面積和疊代（`TreePath`）