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

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Pomocí syntaxe WIQL můžete definovat dotaz jako hypertextový odkaz nebo při použití rozhraní REST API (Work Item Query Language).

Syntaxe WIQL podporuje všechny funkce dostupné prostřednictvím webového portálu Editor Power Query a ještě několik dalších. Můžete zadat pole, která se mají vrátit, a zadat logické seskupení klauzulí dotazu. Kromě toho můžete použít ASOF klauzuli k filtrování na základě přiřazení na základě předchozího data.

Požadavky

Dotaz vrátí pouze ty pracovní položky, pro které máte v oprávnění k uzlu Zobrazit pracovní položky nebo Zobrazit pracovní položky. 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

Dotazovací jazyk pracovní položky má pět částí zobrazených v následujícím fragmentu syntaxe a popsané v následující 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-2020'

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.

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

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

Pokud je čas vynechán v literálu DateTime a parametr dayPrecision 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 2021-12-10 15:00:00.000 představuje 10. prosince 2021 v místním čase. Příklad použití formátu ISO 8601 je následující.

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

Vlastní pole

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, změňte filtr dotazu tak, aby odpovídal následujícímu příkladu.

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. Například @Me označuje osobu, která dotaz spouští. Další informace naleznete v tématu Makra a proměnné dále v tomto článku.
  • 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.

Operátory

Dotazy používají logické výrazy k opravňujícím sadám výsledků. Tyto logické výrazy jsou tvořeny jednou nebo více konjoinovanými operacemi.

Níže jsou uvedeny některé jednoduché operace dotazu.

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 =, <>, >, <, >=, and <= fungují podle očekávání. Například System.ID > 100 dotazy na všechny pracovní položky s ID větší než 100. System.ChangedDate > '01-01-19 12:00:00' dotazy na všechny pracovní položky se změnily po poledne 1. ledna 2019.

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

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. Příklady jsou uvedené níže.

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

Operátory a in operátory contains, under, můžete negovat pomocí .not Operátor nelze negovat ever . Následující příklad se dotazuje na 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í Editor Power Query příklad najde všechny pracovní položky, které byly někdy přiřazeny Jamal Hartnett.

A tady je odpovídající syntaxe 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>'

Makra nebo proměnné

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

@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 polem DateTime . 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ý makro používá @today , 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 dnes je 1.3.19.

WHERE  
   [System.CreatedDate] = @today

Je ekvivalentem:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Je ekvivalentem:

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

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

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

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

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

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

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 (projekt, MyProject), @project se nahradí MyProject v jazyce WIQL. Toto nahrazení spočívá v tom, jak tvůrce dotazů pracovních položek zpracovává makro @project 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.

Předpokládejme, že pracovní položka byla klasifikována v rámci iterační cesty Fabrikam Fiber\Release 1 a přiřazena k Jamal Hartnett před 5. 5. 2022. 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-2022 00:00:00.0000000'

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í.

Následující příklad seřadí pracovní položky jako první podle priority ve vzestupném pořadí (výchozí) a potom podle data vytvoření v sestupném pořadí (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, zadáte 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 propojení. Například následující dotaz vrátí odkazy mezi položkami backlogu produktů a aktivními podřízenými položkami.

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'
    )
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)

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

• 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

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

Ekvivalentní syntaxe WIQL je znázorněna níže.

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í dotaz vrátí všechny typy pracovních položek definované v aktuálním projektu. Dotaz, jak je znázorněno v Editor Power Query, jak je znázorněno na následujícím obrázku.

Ekvivalentní syntaxe WIQL je znázorněná.

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í ID a název návratové sady jako sloupce. Výsledky jsou seřazené podle ID ve vzestupném pořadí.

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 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/2019 00:00:00Z'

Ukázkové klauzule

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

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

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'

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

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [System.Id] [asc | desc]

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>' 
ASOF '3/16/19 12:30'

String a PlainText

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

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

Operátor contains můžete použít k vyhledání podřetězece kdekoli v hodnotě pole.

WHERE [System.Description] contains 'WIQL' 

Oblast a iterace (TreePath)

Operátor můžete použít UNDER pro pole Cesta oblasti a iterace. Operátor UNDER vyhodnotí, jestli je hodnota v podstromu konkrétního uzlu klasifikace. Například následující výraz by se vyhodnotil jako true, pokud by cesta k oblasti byla MyProject\Server\Administration, MyProject\Server\Administration\Feature 1, MyProject\Server\Administration\Feature 2\SubFeature 5 nebo 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 typy polí String, Integer, Double a DateTime. Podívejte se na následující příklad spolu s jeho sémantický ekvivalent.

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í, jestli se hodnota pole rovná nebo se někdy rovná určité hodnotě ve všech předchozích revizích pracovních položek. Typy polí String, Integer, Double a DateTime 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 Jamalovi, Raise 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>'
    )

Související články

• Dotazování na pole, operátory, hodnoty a proměnné
• Pole a atributy pracovní položky
• Informace o spravovaných dotazech
• Definování dotazu