Referenční informace k syntaxi jazyka WIQL (Work Item Query Language)

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Syntaxi WIQL můžete použít k definování dotazu jako hypertextového odkazu nebo při použití rozhraní REST API (Work Item Query Language).

TECHNOLOGIE WIQL podporuje všechny funkce dostupné prostřednictvím Editoru dotazů webového portálu a několik dalších. Můžete zadat pole pro vrácení a logické seskupení klauzulí dotazu. Klauzuli můžete také použít ASOF k filtrování na základě přiřazení k předchozímu datu.

Important

Syntaxe WIQL se používá ke spuštění dotazu pomocí rozhraní REST API Wiql. Rozhraní API vrátí jenom ID pracovních položek bez ohledu na to, která pole zahrnete do SELECT příkazu. Pokud chcete získat úplné informace, (1) získejte ID z WIQL a pak (2) získejte pracovní položky prostřednictvím získání seznamu pracovních položek podle ID a pro konkrétní pole.

Prerequisites

Category	Requirements
Permissions	Zobrazit pracovní položky nebo Zobrazit pracovní položky v tomto uzlu oprávnění nastavená na Povolit. Tato oprávnění jsou obvykle udělena členům skupin Čtenáři a Přispěvatelé pro každý týmový projekt. Další informace najdete v tématu Oprávnění a skupiny.

Přehled dotazovacího jazyka

WIQL má pět částí, jak je znázorněno v následujícím fragmentu syntaxe a popsáno v tabulce. Syntaxe WIQL nerozlišuje malá a velká písmena.

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

Instalací rozšíření Wiql Editor Marketplace můžete vytvářet dotazy pomocí Editoru dotazů a zobrazit syntaxi WIQL. Potom můžete zkopírovat a upravit syntaxi WIQL a spustit dotaz pomocí centra Wiql Playground přidaného do Boards.

Klauzule	Příklad/popis
`SELECT`	Identifikuje pole, která se mají vrátit pro každou pracovní položku. Můžete zadat popisný název nebo název odkazu. Pokud název obsahuje prázdné hodnoty nebo tečky, použijte hranaté závorky (`[]`).
`FROM`	Určuje, jestli má dotaz najít pracovní položky nebo propojení mezi pracovními položkami. - Slouží `FROM WorkItems` k vrácení pracovních položek. – Slouží `FROM workItemLinks` k vrácení propojení mezi pracovními položkami. Další informace najdete v tématu Dotazy týkající se propojení mezi pracovními položkami.
`WHERE`	Určuje kritéria filtru pro dotaz. Další informace najdete v tématu Podmínky filtru (`WHERE`).
`ORDER BY`	Určuje pořadí řazení vrácených pracovních položek. Pro jedno nebo více polí můžete zadat vzestupně (`Asc`) nebo sestupně (`Desc`). Příklad: `ORDER BY [State] Asc, [Changed Date] Desc`
`ASOF`	Určuje historický dotaz tím, že označuje datum, kdy se má filtr použít. Tento dotaz například vrátí všechny uživatelské scénáře definované jako Aktivní 11. února 2025. Zadejte datum podle pokynů uvedených ve vzoru data a času. `ASOF '02-11-2025'`

Note

Dotazy WIQL vytvořené v Azure Boards nesmí překročit 32 K znaků. Systém neumožňuje vytvářet nebo spouštět dotazy, které tuto délku překračují.

Vzor data a času

Vzor data a času, který zadáte pro pole DateTime , by se měl shodovat s tím, který vyberete v profilu. Pokud chcete zobrazit nebo změnit výběr, přečtěte si téma Nastavení uživatelských předvoleb.

Snímek obrazovky s možnostmi rozevíracího seznamu Vzor data v podokně Čas a národní prostředí

Snímek obrazovky znázorňující podokno Čas a národní prostředí s poli Vzor data a Času

Uvozovky (jednoduché nebo dvojité uvozovky jsou podporované) DateTime literály použité ve srovnáních. Musí být ve formátu .NET DateTime místního klientského počítače, na kterém je spuštěn dotaz. Pokud není zadané časové pásmo, DateTime literály jsou v časovém pásmu místního počítače.

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

Pokud je čas vynechán v literálu DateTime a dayPrecision parametr se rovná false, předpokládá se, že čas bude nula (půlnoc). Výchozí nastavení parametru dayPrecision je false.

Nebo můžete zadat formát ISO 8601, který je platný bez ohledu na národní prostředí. ISO 8601 představuje datum a čas od roku, za kterým následuje měsíc, den, hodina, minuty, sekundy a milisekundy. Například 2025-12-10 15:00:00.000 představuje 10. prosince 2025 v místním čase 3:00. Příklad použití formátu ISO 8601 je následující:

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')

Vlastní pole

Do klauzule dotazu můžete přidat vlastní pole. U technologie WIQL je nutné zadat název odkazu pro vlastní pole. U projektů, které používají model zděděného procesu, jsou vlastní pole obvykle označena předem zadaným Custom. názvem a mezerami odebrány. Například:

Přátelský název	Referenční název
`Approver`	`Custom.Approver`
`Request Type`	`Custom.RequestType`
`Scope Estimate`	`Custom.CustomEstimate`

U projektů, které používají místní model procesu XML, se název odkazu definuje definicemi typu pracovní položky XML.

Další informace naleznete v tématu Pole a atributy pracovní položky.

Určení klauzulí filtru (`WHERE`)

Klauzule WHERE určuje kritéria filtru. Dotaz vrátí pouze pracovní položky, které splňují zadaná kritéria. Například následující příklad WHERE klauzule vrátí uživatelské scénáře, které jsou aktivní a které jsou přiřazeny vám.

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

Pořadí, ve kterém se logické operátory vyhodnocují, můžete řídit tak, že je uzavřete do závorek a seskupíte kritéria filtru. Pokud chcete například vrátit pracovní položky, které jsou vám přiřazeny nebo které jste zavřeli, použijte následující příklad.

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

Podmínky filtru

Každá podmínka filtru se skládá ze tří částí, z nichž každá musí odpovídat následujícím pravidlům:

Pole: Můžete zadat název odkazu nebo popisný název. Následující příklady jsou platná syntaxe WIQL:
- Název odkazu: SELECT [System.AssignedTo] ...
- Popisný název s mezerami: SELECT [Assigned To] ...
- Názvy bez mezer nevyžadují hranaté závorky: SELECT ID, Title ...
Operátor: Platné hodnoty jsou uvedeny v části Operátory dále v tomto článku.
Hodnota pole: V závislosti na zadaném poli můžete zadat jednu z následujících tří hodnot.
- Hodnota literálu musí odpovídat datovému typu hodnoty pole.
- Proměnná nebo makro označující určitou hodnotu. Označuje například osobu, @Me která dotaz spouští. Další informace naleznete v tématu Makra a proměnné.
- Název jiného pole. Můžete například najít [Assigned to] = [Changed by] pracovní položky, které jsou přiřazené osobě, která pracovní položku naposledy změnila.

Popis a referenční názvy všech systémově definovaných polí naleznete v tématu Index polí pracovní položky.

Operators

Dotazy používají logické výrazy k opravňujícím sadám výsledků. Tyto logické výrazy tvoří jednu nebo více konjovovaných operací.

Některé jednoduché operace dotazu jsou následující:

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

Následující tabulka shrnuje všechny podporované operátory pro různé typy polí. Další informace o jednotlivých typech polí najdete v tématu Pole a atributy pracovní položky.

Operátory =, , <>, ><>=a <= fungují podle očekávání. Například System.ID > 100 dotazy na všechny pracovní položky s ID větším než 100. System.ChangedDate > '01-01-25 12:00:00' dotazy na všechny pracovní položky se změnily po poledne 1. ledna 2025.

Kromě těchto základních operátorů existují určité chování a operátory specifické pro určité typy polí.

Note

Operátory, které máte k dispozici, závisí na vaší platformě a verzi. Další informace najdete v tématu Stručná referenční příručka k dotazům.

Typ pole	Podporované operátory
`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`

Logické seskupení

Termíny AND a OR v typickém logickém smyslu můžete použít k vyhodnocení dvou klauzulí. Můžete použít podmínky AND EVER a OR EVER při zadávání operátoru WAS EVER . Logické výrazy můžete podle potřeby seskupit a dále je spojit. Následující příklady ukazují.

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>'
        )
    )

Můžete negovat contains, undera in operátory pomocí not. Operátor nelze negovat ever . Následující příklad dotazuje všechny pracovní položky, které nejsou přiřazeny pod podstrom .Fabrikam Fiber\Account Management

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

Příklad dotazu, kdy byl přiřazen

Následující příklad Editoru dotazů najde všechny pracovní položky, které byly někdy přiřazeny Jamal Hartnett.

Snímek obrazovky s dotazem Editor Power Query, plochým seznamem, byl někdy přiřazený.

Odpovídající syntaxe WIQL je následující:

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>'

Makra nebo proměnné

Následující tabulka uvádí makra nebo proměnné, které můžete použít v dotazu WIQL.

Macro	Usage
`@Me`	Pomocí této proměnné můžete automaticky vyhledat alias aktuálního uživatele v poli, které obsahuje aliasy uživatelů. Můžete například najít pracovní položky, které jste otevřeli, pokud nastavíte `Field` sloupec na `Activated By`, `Operator` sloupec na `=`a `Value` sloupec na `@Me`hodnotu .
`@CurrentIteration`	Tato proměnná slouží k automatickému filtrování pracovních položek přiřazených aktuálnímu sprintu pro vybraný tým na základě vybraného kontextu týmu.
`@Project`	Tato proměnná slouží k hledání pracovních položek v aktuálním projektu. Můžete například najít všechny pracovní položky v aktuálním projektu, pokud nastavíte `Field` sloupec na `Team Project`, `Operator` sloupec na `=`a `Value` sloupec na `@Project`.
`@StartOfDay` `@StartOfWeek` `@StartOfMonth` `@StartOfYear`	Pomocí těchto maker můžete filtrovat `DateTime` pole na základě začátku aktuálního dne, týdne, měsíce, roku nebo posunu na jednu z těchto hodnot. Pokud například nastavíte `Field` sloupec na hodnotu , `Created Date` sloupec nastavíte na `Operator>=`hodnotu `Value` a sloupec na `@StartOfMonth - 3`hodnotu ., můžete například najít všechny položky vytvořené za posledních tři měsíce.
`@Today`	Tato proměnná slouží k hledání pracovních položek, které souvisejí s aktuálním datem nebo dřívějším datem. Proměnnou `@Today` můžete také upravit odečtením dnů. Všechny položky aktivované v posledním týdnu můžete najít například v případě, že nastavíte `Field` sloupec na `Activated Date`hodnotu , `Operator` sloupec na `>=`hodnotu a `Value` sloupec na `@Today - 7`hodnotu .
`[Any]`	Tato proměnná slouží k hledání pracovních položek, které se vztahují k libovolné hodnotě definované pro konkrétní pole.

`@me` makro

Makro @me nahradí název integrovaného účtu systému Windows uživatele, který spustí dotaz. Následující příklad ukazuje, jak použít makro a ekvivalentní statický příkaz. Makro je určeno pro použití s poli identit, jako Assigned Toje například .

WHERE  
   [System.AssignedTo] = @Me

`@today` makro

Makro můžete použít @today s libovolným DateTime polem. Toto makro nahrazuje půlnoc aktuálního data v místním počítači, na kterém se spouští dotaz. Můžete také zadat @today+x nebo @today-y použít celočíselné posuny po x dnech po @today a y před @today, v uvedeném pořadí. Dotaz, který používá @today makro, může v závislosti na časovém pásmu, ve kterém se spouští, vrátit různé sady výsledků.

Následující příklady předpokládají, že dnešní den je 3. 3. 2025.

WHERE  
   [System.CreatedDate] = @today

Je ekvivalentem:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Je ekvivalentem:

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

`@StartOfDay`, , `@StartOfWeek`, `@StartOfMonth@StartOfYear`makra

Makra můžete použít @StartOf... s libovolným DateTime polem. Toto makro nahrazuje půlnoc aktuálního dne, začátek týdne, začátek měsíce nebo začátek roku v místním počítači, na kterém se dotaz spouští.

Tato makra přijímají modifikační řetězec, který má formát (+/-)nn(y|M|w|d|h|m). Podobně jako u @Today makra můžete zadat celočíselné posuny plus nebo minus. Pokud kvalifikátor časových jednotek vynecháte, ve výchozím nastavení se nastaví přirozené období funkce. Například trasa @StartOfWeek("+1") je stejná jako @StartOfWeek("+1w"). Pokud je znaménko plus/minus (+/-) vynecháno, předpokládá se plus.

Tato syntaxe umožňuje vnořit modifikátory a vysazení dotazu dvakrát. Klauzule Closed Date >= @StartOfYear - 1 například filtruje pracovní položky uzavřené od minulého roku. Když ho upravíte na Closed Date >= @StartOfYear('+3M') - 1, vyloučí pracovní položky uzavřené během prvních tří měsíců minulého roku. Následující syntaxe WIQL ukazuje:

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

Následující příklady předpokládají, že dnes je 5. 4. 2025.

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

Je ekvivalentem:

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

And

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

Je ekvivalentem:

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

Vlastní makra

TECHNOLOGIE WIQL také podporuje libovolná vlastní makra. Jakýkoli řetězec, který je předponou, @ se považuje za vlastní makro a nahradí se. Hodnota nahrazení vlastního makra se načte z kontextového parametru metody dotazu v objektovém modelu. Následující metoda je rozhraní API používané pro makra:

public WorkItemCollection Query(string wiql, IDictionary context)

Kontextový parametr obsahuje páry klíč-hodnota pro makra. Pokud například kontext obsahuje dvojici klíč-hodnota (project, MyProject), pak @project se nahradí MyProject v WIQL. Tímto nahrazením je způsob, jakým tvůrce dotazů pracovních položek zpracovává @project makro v sadě Visual Studio.

Určení historických dotazů (`ASOF`)

Klauzuli ASOF v dotazu můžete použít k filtrování pracovních položek, které splňují zadané podmínky filtru, jak byly definovány v určitém datu a čase.

Note

V tvůrci dotazů v sadě Visual Studio nemůžete vytvářet ASOF dotazy. Pokud vytvoříte soubor dotazu (.wiq), který obsahuje ASOF klauzuli, a pak ji načtete v sadě Visual Studio, ASOF bude klauzule ignorována.

Předpokládejme, že pracovní položka byla klasifikována do Iteration PathFabrikam Fiber\Release 1 5. 5. 2025 a přiřazena k "Jamal Hartnett". Pracovní položka byla však nedávno přiřazena k Raisa Pokrovskaya a přesunula se na novou iterační cestu vydané verze 2. Následující příklad dotazu vrátí pracovní položky přiřazené Jamal Hartnett, protože dotaz je založen na stavu pracovních položek od předchozího data a času.

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

Pokud není zadán žádný čas, technologie WIQL používá půlnoc. Pokud není zadáno žádné časové pásmo, technologie WIQL použije časové pásmo místního klientského počítače.

Nastavení pořadí řazení (`ORDER BY`)

Klauzuli můžete použít ORDER BY k seřazení výsledků dotazu podle jednoho nebo více polí ve vzestupném nebo sestupném pořadí.

Note

Předvolby řazení sql serveru na datové vrstvě určují výchozí pořadí řazení. Pomocí parametrů ascdesc ale můžete zvolit explicitní pořadí řazení.

Následující příklad nejprve seřadí pracovní položky Priority vzestupně (výchozí) a potom sestupně 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

Dotaz na propojení mezi pracovními položkami

Chcete-li vrátit propojení mezi pracovními položkami, zadejte FROM WorkItemLinks. Podmínky filtru v WHERE klauzuli se můžou vztahovat na odkazy nebo na jakoukoli pracovní položku, která je zdrojem nebo cílem odkazu. Následující příklad vrátí propojení mezi Product Backlog Items a jejich aktivní podřízené položky.

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)

Následující tabulka shrnuje rozdíly mezi dotazy pracovních položek a dotazy na propojení mezi pracovními položkami.

Klauzule	Pracovní položky	Propojení mezi pracovními položkami
`FROM`	`FROM WorkItems`	`FROM WorkItemLinks`
`WHERE`	`[FieldName] = Value`	Zadejte jednu nebo více z následujících možností: `[Source].[FieldName] = Value` `[Target].[FieldName] = Value` `[System.Links.LinkType] = 'LinkName'`
`MODE`	nejde použít	Zadejte jednu z následujících možností: - `MODE (MustContain)`: (Výchozí) Vrátí pouze `WorkItemLinkInfo` záznamy, ve kterých jsou splněna kritéria zdroje, cíle a propojení. - `MODE (MayContain)`: Vrátí `WorkItemLinkInfo` záznamy pro všechny pracovní položky, které splňují kritéria zdroje a propojení, i když žádná propojená pracovní položka nesplňuje cílová kritéria. - `MODE (DoesNotContain)`: Vrátí `WorkItemLinkInfo` záznamy pro všechny pracovní položky, které vyhovují zdroji, pouze pokud žádná propojená pracovní položka nesplňuje kritéria propojení a cíle. - `MODE (Recursive)`: Používá se pro stromové dotazy (`[System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'`). Typ odkazu musí být topologie stromové struktury a směr dopředu. Vrátí `WorkItemLinkInfo` záznamy pro všechny pracovní položky, které vyhovují zdroji, rekurzivně pro cíl. `ORDER BY` a `ASOF` nejsou kompatibilní se stromovými dotazy.
`RETURNS`	`WorkItemQueryResult`	`WorkItemLink`

Můžete zadat jeden z následujících názvů typů systémových propojení.

Můžete zadat jeden z následujících názvů typů systémových odkazů nebo vlastní typ propojení definovaný pomocí místního procesu XML.

System.LinkTypes.Hierarchy-Forward
System.LinkTypes.Related
System.LinkTypes.Dependency-Predecessor
System.LinkTypes.Dependency-Successor
Microsoft.VSTS.Common.Affects-Forward (proces CMMI)

Další informace naleznete v tématu Odkaz na typ odkazu.

Příklad dotazu typu stromu

Note

ORDER BY a ASOF nejsou kompatibilní se stromovými dotazy. Nezahrnujte tyto klauzule do stromových dotazů.

Následující dotaz vrátí všechny typy pracovních položek definované v aktuálním projektu. Editor dotazů zobrazí dotaz, jak je znázorněno na následujícím obrázku.

Snímek obrazovky Editor Power Query, stromového dotazu, všech pracovních položek a stavů

Ekvivalentní syntaxe WIQL je následující:

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)

Příklad dotazu direct-link

Následující příklad vrátí všechny typy pracovních položek definované v aktuálním projektu. Editor dotazů zobrazí dotaz, jak je znázorněno na následujícím obrázku.

Snímek obrazovky s Editor Power Query, dotazem direct-link, všemi pracovními položkami a stavy

Ekvivalentní syntaxe WIQL je následující:

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)

Další příklady dotazů

Následující typický příklad dotazu WIQL používá názvy odkazů pro pole. Dotaz vybere pracovní položky (není zadaný žádný typ pracovní položky) s hodnotou Priority=1. Dotaz vrátí hodnotu ID a Title vrácenou sadu jako sloupce. Výsledky jsou seřazené ID vzestupně.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Model data a času

Vzor data a času zadáte podle jednoho ze dvou vzorů:

Formát vzorce data a času pochází z vašich uživatelských předvoleb, času a národního prostředí.
Vzor určený standardem UTC, který se řídí tímto vzorem (s písmenem Z připojeným k datu a času).

AND [System.ChangedDate] >= '1/1/2025 00:00:00Z'

Ukázkové klauzule

Následující ukázkové příkazy zobrazují konkrétní opravňující klauzule.

Klauzule	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` (Časový filtr)	`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'`

String a PlainText

Řetězcové literály uvozovek (jednoduché nebo dvojité uvozovky jsou podporovány) ve srovnání s polem String nebo PlainText polem. Řetězcové literály podporují všechny znaky Unicode.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Pomocí operátoru contains můžete vyhledat podřetězece kdekoli v hodnotě pole.

WHERE [System.Description] contains 'WIQL'

Oblast a iterace (`TreePath`)

Operátor můžete použít UNDER pro Area Path pole a Iteration Path pole. Operátor UNDER vyhodnotí, jestli je hodnota v podstromu konkrétního uzlu klasifikace. Například následující výraz se vyhodnotí jako true, pokud Area Path byl MyProject\Server\Administration, MyProject\Server\Administration\Feature 1, MyProject\Server\Administration\Feature 2\SubFeature 5nebo jakýkoli jiný uzel v podstromu.

WHERE [System.AreaPath] UNDER `MyProject\Server\Administration`

Modifikátory a speciální operátory

Ve výrazu dotazu můžete použít některé modifikátory a speciální operátory.

Pomocí operátoru IN můžete vyhodnotit, jestli je hodnota pole rovna libovolné sadě hodnot. Tento operátor je podporován pro Stringtypy polí , Integer, Doublea DateTime pole. Následující příklad a jeho sémantický ekvivalent to demonstrují.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Operátor EVER se používá k vyhodnocení, zda se hodnota pole rovná nebo někdy rovná určité hodnotě ve všech předchozích revizích pracovních položek. Typy Stringpolí , Integer, Doublea DateTime pole podporují tento operátor. Operátor má alternativní syntaxe EVER . Například následující fragmenty kódu se dotazují, jestli byly všechny pracovní položky někdy přiřazeny Jamal, Raisa nebo Christie.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Použití Copilotu k zápisu, opravě a optimalizaci WIQL

Pomoc s vytvářením, opravou nebo optimalizací dotazů WIQL můžete použít asistenta AI (například GitHub Copilot nebo jiné kopírovací objekty). Zachází s Copilotem jako s podporou produktivity , ne jako autoritativním zdrojem, a před spuštěním generovaného dotazu vždy zkontrolujte a otestujte všechny vygenerované dotazy.

Pokyny a osvědčené postupy:

Možnosti: Copilot dokáže přeložit požadavky ve formátu prostého jazyka na JAZYK WIQL, opravit chyby syntaxe (chybějící závorky, chybějící čárky, nesprávná klíčová slova), převést seznamy SELECT mezi popisnými názvy a názvy odkazů, vygenerovat ASOF klauzule nebo literály kalendářních dat a přepsat klauzuli tak, aby se sady výsledků zúžily nebo rozšířily.
Ověření: Vždy ověřte vygenerované WIQL v Editoru dotazů nebo v bezpečném testovacím projektu. Před použitím zkontrolujte makra (například @Me, @Today) a formáty kalendářních dat závislých na národním prostředí.
Zabezpečení: Do výzev nikdy nevkládejte tajné kódy, přístupové tokeny ani žádné privátní připojovací řetězce. Odeberte nebo redigujte všechny citlivé hodnoty v příkladech, které předáte do copilotu.
Výkon: Požádejte Copilot, aby minimalizoval počet datových částí výsledků (vrácené pouze potřebná pole), přidal odpovídající filtry WHERE a vyhnul se příliš širokému IN používání nebo nevázaných LIKE hledání. Zapamatujte si limit znaků 32 K pro dotazy WIQL.
Kontrola hraničních případů: Potvrďte chování historických (ASOF) dotazů, dotazů stromové struktury nebo propojení (FROM workItemLinks) a WAS EVER/EVER operátorů, které kontrolují revize – můžou být složitější a můžou vyžadovat ruční ladění.

Příklad : Vygenerování WIQL z prosté angličtiny:

Výzva: Návrat ID a název aktivních chyb přiřazených v @Me projektu Fabrikam a změněný za posledních 30 dnů Seřadit podle ChangedDate desc."

Copilot vytváří:

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

Automatizace dotazů WIQL pomocí rozhraní REST API a umělé inteligence

Pomocí asistentů AI, jako je Copilot, můžete automatizovat dvoustupňový proces rozhraní REST API WIQL:

Pomocí rozhraní REST API Pro dotazy podle Wiql načtěte ID pracovních položek odpovídajících vaší WIQL.
Pomocí rozhraní API Získat pracovní položky načtěte úplné podrobnosti těchto ID.

AI vám může pomoct:

Vygenerujte WIQL z prostého jazyka a pak zřetězení dvou volání rozhraní API v kódu (například Python, PowerShell nebo JavaScript).
Formátování a shrnutí výsledků pro řídicí panely nebo sestavy

Tip

Podrobnosti o rozhraní REST API najdete v tématu Dotaz podle Wiql (REST API).

Příklad: Automatizace WIQL pomocí Pythonu a umělé inteligence

Předpokládejme, že chcete zobrazit seznam názvů a stavů všech aktivních chyb v projektu.

Výzva ke zkopírování:
Napište kód Pythonu, který používá rozhraní Azure DevOps REST API k výpisu názvů a stavů všech aktivních chyb v projektu. Pomocí TECHNOLOGIE WIQL získejte ID a pak načtěte podrobnosti o těchto ID."

Pomocí Copilotu můžete vygenerovat kód takto:

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.")

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-08

Sdílet prostřednictvím

Referenční informace k syntaxi jazyka WIQL (Work Item Query Language)

Prerequisites

Přehled dotazovacího jazyka

Vzor data a času

Vlastní pole

Určení klauzulí filtru (WHERE)

Podmínky filtru

Operators

Logické seskupení

Příklad dotazu, kdy byl přiřazen

Makra nebo proměnné

@me makro

@today makro

@StartOfDay, , @StartOfWeek, @StartOfMonth@StartOfYearmakra

Vlastní makra

Určení historických dotazů (ASOF)

Nastavení pořadí řazení (ORDER BY)

Dotaz na propojení mezi pracovními položkami

Příklad dotazu typu stromu

Příklad dotazu direct-link

Další příklady dotazů

Model data a času

Ukázkové klauzule

String a PlainText

Oblast a iterace (TreePath)

Modifikátory a speciální operátory

Použití Copilotu k zápisu, opravě a optimalizaci WIQL

Automatizace dotazů WIQL pomocí rozhraní REST API a umělé inteligence

Související obsah

Váš názor

Další materiály

Určení klauzulí filtru (`WHERE`)

`@me` makro

`@today` makro

`@StartOfDay`, , `@StartOfWeek`, `@StartOfMonth@StartOfYear`makra

Určení historických dotazů (`ASOF`)

Nastavení pořadí řazení (`ORDER BY`)

Oblast a iterace (`TreePath`)